File Conventions

Special filenames and exports that Juice recognizes in the app/routes/directory.

File Conventions

Filename	Purpose	Receives
`layout.tsx`	Wraps all routes in the current directory and subdirectories. Chains root to leaf.	`{ children, request }`
`middleware.ts`	Runs before all routes in the current directory. Onion model.	`(req, next)`
`loading.tsx`	Suspense fallback for routes in the current directory.	No props
`error.tsx`	Error boundary fallback for routes in the current directory.	`{ error }`
`home.tsx`	Index route for the current directory (`/`).	Standard page props
`[param].tsx`	Dynamic route segment. The bracket name becomes a typed param.	Standard page props
`global.css`	Global stylesheet. Import from layout to apply site-wide.	n/a

Export Conventions

These named exports are recognized on route files (.tsx and .ts).

Export	Type	Description
`default`	React component	The page component. Rendered as a React Server Component by default.
`response`	`{ head?, headers?, boundary? }`	Unified response configuration. Preferred over individual exports.
`response.head`	`{ title?, description? }`	Metadata injected into the HTML head.
`response.headers`	`Record<string, string> \| (req) => Record<string, string>`	Custom response headers. Can be static or a function of the request.
`response.boundary`	`boolean \| 'shell'`	Per-route streaming mode override.
`headers`	`Record<string, string>`	Legacy: custom response headers. Use `response.headers` instead.
`metadata`	`{ title?, description? }`	Legacy: page metadata. Use `response.head` instead.
`prerender`	`boolean`	When true, sets immutable cache headers on the response.
`GET`	`(req: Request) => Response`	HTTP GET handler. Route acts as an API endpoint.
`POST`	`(req: Request) => Response`	HTTP POST handler.
`PUT`	`(req: Request) => Response`	HTTP PUT handler.
`DELETE`	`(req: Request) => Response`	HTTP DELETE handler.

Directory Structure Example

app/
  routes/
    layout.tsx           # Root layout (wraps everything)
    global.css           # Global styles
    home.tsx             # / route
    middleware.ts        # Root middleware
    about.tsx            # /about route
    blog/
      layout.tsx         # Blog layout (nested)
      loading.tsx        # Blog suspense fallback
      index.tsx          # /blog route
      [slug].tsx         # /blog/:slug route
    admin/
      middleware.ts      # Auth middleware
      layout.tsx         # Admin layout
      dashboard.tsx      # /admin/dashboard route
      error.tsx          # Admin error boundary
    api/
      middleware.ts      # CORS middleware
      health.ts          # /api/health (GET handler)
      users.ts           # /api/users (GET, POST handlers)
  components/
    counter.tsx          # 'use client' component

CLI

Router Options