LILYLILYDOCS
HomepageLogin
Docs/CLI/nextjs

lly nextjs

Compile a Next.js App Router project to portable WASM bricks.

lly nextjs is a util plugin that turns a Next.js App Router project into one or more bricks. It reads the app/ directory, walks layouts, pages, route handlers, and server actions, and lowers the whole thing through frontend-js to wasm32-wasi. The output runs locally with lly run or ships to the fleet with lly void deploy.

The plugin is installed by default. If it is missing, run lly plugin install nextjs. Inside any directory that contains an app/ folder and a package.json, the subcommands below operate on the project rooted at the current working directory.

Subcommands

  • routes — discover and print every route in app/. Shows dynamic segments, parallel slots, intercepting routes, and which routes are static, ISR, or fully dynamic.
  • build — bundle every route to a separate .brick under .nextjs-bricks/<route>/. One brick per page plus shared layout bricks. Reproducible and content-addressed.
  • dev — start a dev HTTP server on 127.0.0.1:3000. Serves SSR through the brick cache and reloads on file change via an SSE channel at /_lly/hmr/stream.
  • render — render one route to stdout for debugging. Accepts --path /blog/hello and prints the full HTML response including head and hydrate manifest.
  • export — pre-render every static page to HTML and copy hydrate bundles plus public/ into out/. Drops a sample nginx.conf next to it. Use this for fully static sites.
  • void — single-brick mode. Packs the entire project, including the HTTP server, into one void.brick that runs inside a CAP. This is the brick you hand to lly void deploy.

Synopsis

lly nextjs <SUBCOMMAND> [OPTIONS]

Common options: --profile es2023 (JS target), --multi (allow multi-brick output where supported), -v for staged timings, --out <DIR> to override the default output directory.

The deploy path

The single command most projects need is lly nextjs void. It produces one self-contained brick a few megabytes in size, ready for lly void deploy. The pipeline is route discovery, per-route compilation, asset collection, HTTP-server splice, and manifest sealing.

compile a Next.js project to one brick
$ lly nextjs void → nextjs v0.14.1 · project: ./blog routes 11 found (8 static · 2 isr · 1 dynamic) compile frontend-js v0.11.4 · profile=es2023 bundle 12 wasm modules · 1 merged 4.2 s assets public/ 18 files · css 3 · fonts 2 61 ms hydrate esbuild · 4 entry points · vendor shared 1.1 s seal wasm32-wasi · single-brick · http server 88 ms ✓ wrote void.brick (3.7 MB, sha256:5e21…b9d4) next: lly void deploy ./void.brick

Hand void.brick to lly void deploy and the platform records ownership, picks a CAP, and returns a live URL such as https://lazy-fox.app.lilylabs.io. For the end-to-end walkthrough see Deploy a Next.js app.

Discover routes

Before building it is often useful to see what the plugin sees. lly nextjs routes prints the route table the bundler will work from. Dynamic segments are bracketed, intercepting routes are marked, and parallel slots are listed under their host layout.

list routes
$ lly nextjs routes / static app/page.tsx /about static app/about/page.tsx /blog isr=60 app/blog/page.tsx /blog/[slug] isr=60 app/blog/[slug]/page.tsx /api/feed dynamic app/api/feed/route.ts /(.)photo/[id] intercept app/(.)photo/[id]/page.tsx ✓ 11 routes

Build, dev, render, export

lly nextjs build emits one brick per route under .nextjs-bricks/<route>/page.brick. This mode is useful when you want to inspect or ship individual routes separately. lly nextjs dev watches your sources and SSR-renders through the brick cache; bricks are rebuilt on demand, so the first request to a changed route is the slow one. lly nextjs render --path /blog/hello prints the full HTML response for one route, including the head, the hydrate manifest, and any __NEX_META__ markers. lly nextjs export walks every page that does not opt out of static generation and writes out/<route>/index.html plus hydrate bundles, ready to be served by nginx.

What the plugin understands

The nextjs plugin tracks current Next.js App Router conventions: layout.tsx, page.tsx, loading.tsx, error.tsx, not-found.tsx, template.tsx, route.ts, proxy.ts (the LILY name for middleware), instrumentation.ts, parallel routes (@slot), intercepting routes ((.)x, (..)x, (...)x), generateStaticParams, generateMetadata, export const revalidate, export const dynamic, export const fetchCache, server actions via 'use server', and client components via 'use client'. Static metadata files such as favicon.ico, icon.png, sitemap.ts, robots.ts, and manifest.ts are discovered and served automatically.

Exit codes

  • 0 — success.
  • 2 — usage error or no app/ directory in the current working tree.
  • 3 — compile failure in one or more routes. The offending route and diagnostic are printed.
  • 4 — plugin error. The frontend or runtime dependency is missing.

See also