Next Shell Builder

Building with @jonmatum/next-shell

This skill gives you everything needed to build a Next.js application using @jonmatum/next-shell. Use it when:

• Scaffolding a new app from scratch
• Adding pages, layouts, or features to an existing next-shell app
• Composing primitives into custom components
• Wiring up authentication, theming, or navigation
• Using hooks, formatters, or the command bar

Quick setup (new app)

npx degit jonmatum/next-shell/templates/starter my-app
cd my-app && pnpm install && pnpm dev

Or manually:

pnpm add @jonmatum/next-shell next@^15 react@^19 react-dom@^19 tailwindcss@^4
pnpm add -D @tailwindcss/postcss@^4

postcss.config.mjs (required)

export default { plugins: { '@tailwindcss/postcss': {} } };

globals.css (required)

@import 'tailwindcss';
@source "node_modules/@jonmatum/next-shell/dist/**/*.{js,cjs}";
@import '@jonmatum/next-shell/styles/preset.css';

Both tailwindcss AND @tailwindcss/postcss are required dependencies. Without them, @import 'tailwindcss' in globals.css will fail with "Can't resolve 'tailwindcss'".

The @source line is mandatory — Tailwind v4 skips node_modules by default.

Subpath imports (complete map)

Hard rules

1. No raw colors. Every color must use semantic tokens: bg-background, text-foreground, border-border, text-primary, bg-destructive, text-muted-foreground, etc. Never use bg-white, text-gray-500, #hex, rgb(), or oklch() in component code.

2. 'use client' is explicit. Any file using hooks, event handlers, or browser APIs needs 'use client' at the top. Server Components are the default in Next.js App Router.

3. Import from subpaths, not the root. Use @jonmatum/next-shell/primitives not @jonmatum/next-shell. Tree-shaking depends on subpath imports.

4. Server-safe imports for RSC. In Server Components, import from /layout/server, /providers/server, or /auth/server — never from the client-boundary barrels.

App shell pattern

// app/(shell)/layout.tsx
'use client';

import { usePathname } from 'next/navigation';
import {
  AppShell, TopBar, Footer, Sidebar, SidebarContent, SidebarHeader,
  SidebarFooter, SidebarNav, SidebarSeparator, SidebarTrigger,
  Breadcrumbs, CommandBarActions, buildNav,
} from '@jonmatum/next-shell/layout';
import type { NavConfig } from '@jonmatum/next-shell/layout';

const NAV: NavConfig = [
  { id: 'dashboard', label: 'Dashboard', href: '/dashboard', icon: <HomeIcon /> },
  { id: 'settings', label: 'Settings', href: '/settings', icon: <SettingsIcon />,
    children: [
      { id: 'profile', label: 'Profile', href: '/settings/profile' },
      { id: 'billing', label: 'Billing', href: '/settings/billing', requires: 'billing' },
    ],
  },
  { id: 'admin', label: 'Admin', href: '/admin', icon: <ShieldIcon />, requires: 'admin' },
];

export default function ShellLayout({ children }: { children: React.ReactNode }) {
  const pathname = usePathname();
  const permissions = ['billing']; // from your auth system
  const { items, breadcrumbs } = buildNav({ config: NAV, pathname, permissions });

  return (
    <AppShell
      commandBar
      sidebar={
        <Sidebar>
          <SidebarHeader>
            <span className="text-lg font-bold">My App</span>
          </SidebarHeader>
          <SidebarContent>
            <SidebarNav items={items} />
          </SidebarContent>
          <SidebarFooter>
            <span className="text-sm text-muted-foreground">v1.0</span>
          </SidebarFooter>
        </Sidebar>
      }
      topBar={
        <TopBar
          left={<><SidebarTrigger /><Breadcrumbs config={NAV} pathname={pathname} permissions={permissions} /></>}
          right={<ThemeToggleDropdown />}
        />
      }
      footer={<Footer>Built with next-shell</Footer>}
    >
      <CommandBarActions config={NAV} pathname={pathname} permissions={permissions} />
      {children}
    </AppShell>
  );
}

Page pattern

// app/(shell)/dashboard/page.tsx
'use client';

import { PageHeader, ContentContainer } from '@jonmatum/next-shell/layout';
import { Card, CardContent, CardHeader, CardTitle, Button } from '@jonmatum/next-shell/primitives';
import { formatCurrency, formatRelativeTime } from '@jonmatum/next-shell/formatters';

export default function DashboardPage() {
  return (
    <>
      <PageHeader
        title="Dashboard"
        description="Overview of your account"
        actions={<Button>New project</Button>}
      />
      <ContentContainer size="lg" className="py-6 space-y-6">
        <div className="grid gap-4 md:grid-cols-3">
          <Card>
            <CardHeader><CardTitle>Revenue</CardTitle></CardHeader>
            <CardContent>
              <p className="text-2xl font-bold">{formatCurrency(48295, { currency: 'USD' })}</p>
            </CardContent>
          </Card>
        </div>
      </ContentContainer>
    </>
  );
}

Auth pattern

// app/providers.tsx
'use client';

import { AppProviders } from '@jonmatum/next-shell/providers';
import { AuthProvider } from '@jonmatum/next-shell/auth';
import { createMockAuthAdapter } from '@jonmatum/next-shell/auth/mock';

const mockAuth = createMockAuthAdapter({
  user: { id: '1', name: 'Demo User', email: 'demo@example.com', roles: ['admin'] },
});

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <AppProviders themeProps={{ defaultTheme: 'system', enableSystem: true }}>
      <AuthProvider adapter={mockAuth}>
        {children}
      </AuthProvider>
    </AppProviders>
  );
}

Auth guards in pages

import { SignedIn, SignedOut, RoleGate, useUser } from '@jonmatum/next-shell/auth';

function AdminPage() {
  const user = useUser();
  return (
    <>
      <SignedOut><p>Please sign in</p></SignedOut>
      <SignedIn>
        <p>Welcome, {user?.name}</p>
        <RoleGate role="admin" fallback={<p>Admin access required</p>}>
          <AdminPanel />
        </RoleGate>
      </SignedIn>
    </>
  );
}

Hooks cheat sheet

import {
  useDisclosure,      // { isOpen, open, close, toggle, onOpenChange }
  useLocalStorage,    // [value, setValue] — persists across sessions
  useCopyToClipboard, // { copy, isCopied }
  useHotkey,          // useHotkey('k', callback, { meta: true })
  useBreakpoint,      // { current, isMobile, isDesktop }
  useDebouncedValue,  // debounced version of a value
} from '@jonmatum/next-shell/hooks';

Error pages

// app/not-found.tsx (Server Component — import from /layout/server)
import { NotFound } from '@jonmatum/next-shell/layout/server';
export default function NotFoundPage() { return <NotFound />; }

// app/error.tsx (Client Component)
'use client';
import { ErrorPage } from '@jonmatum/next-shell/layout';
export default function ErrorBoundary({ error, reset }: { error: Error; reset: () => void }) {
  return <ErrorPage status="500" title="Something went wrong" description={error.message}
    actions={<Button again</Button>} />;
}

Theming

Brand overrides (JS)

import type { BrandOverrides } from '@jonmatum/next-shell/tokens';

const brand: BrandOverrides = {
  light: { primary: 'oklch(0.6 0.2 145)', 'primary-foreground': 'oklch(1 0 0)' },
  dark: { primary: 'oklch(0.75 0.15 145)' },
  radius: '0.75rem',
};

<ThemeProvider brand={brand}>{children}</ThemeProvider>

Preset palettes (CSS)

@import '@jonmatum/next-shell/styles/preset.css';
@import '@jonmatum/next-shell/styles/presets/green.css';

Available: green.css, neutral.css, orange.css, red.css, violet.css

Generate from hex

npx next-shell-theme --color '#10b981' --format both

Semantic token reference

Colors (all have Tailwind utilities)

Surface pairs: background/foreground, card/card-foreground, popover/popover-foreground, muted/muted-foreground, accent/accent-foreground, primary/primary-foreground, secondary/secondary-foreground, destructive/destructive-foreground, success/success-foreground, warning/warning-foreground, info/info-foreground

Standalone: border, input, ring, overlay

Sidebar: sidebar-background, sidebar-foreground, sidebar-primary, sidebar-primary-foreground, sidebar-accent, sidebar-accent-foreground, sidebar-border, sidebar-ring

Charts: chart-1 through chart-5

Other tokens

• Radius: rounded-sm, rounded-md, rounded-lg, rounded-xl (all derived from --radius)
• Motion: duration-fast (150ms), duration-normal (250ms), duration-slow (400ms)
• Easing: ease-standard, ease-emphasized, ease-decelerate, ease-accelerate
• Shadows: shadow-xs, shadow-sm, shadow-md, shadow-lg, shadow-xl, shadow-2xl

Composition recipes

DatePicker

import { Button, Calendar, Popover, PopoverContent, PopoverTrigger } from '@jonmatum/next-shell/primitives';
import { cn } from '@jonmatum/next-shell/core';

DataTable

import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '@jonmatum/next-shell/primitives';
// + @tanstack/react-table for sorting/filtering/pagination

Combobox

import { Command, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList,
  Popover, PopoverContent, PopoverTrigger } from '@jonmatum/next-shell/primitives';

Common patterns

Toast notifications

import { toast } from 'sonner'; // direct import, not from next-shell

toast.success('Saved!');
toast.error('Failed', { description: 'Try again' });
toast.promise(saveData(), { loading: 'Saving...', success: 'Done!', error: 'Failed' });

Form with validation

import { Form, FormControl, FormField, FormItem, FormLabel, FormMessage,
  Input, Button } from '@jonmatum/next-shell/primitives';
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';

Dialog with useDisclosure

import { useDisclosure } from '@jonmatum/next-shell/hooks';
import { Dialog, DialogContent, DialogTitle, Button } from '@jonmatum/next-shell/primitives';

function MyDialog() {
  const { isOpen, open, onOpenChange } = useDisclosure();
  return (
    <>
      <Button
      <Dialog open={isOpen}
        <DialogContent><DialogTitle>Title</DialogTitle></DialogContent>
      </Dialog>
    </>
  );
}

Source: jonmatum/next-shell — distributed by TomeVault.