Skip to content

Add standalone self-host output and align init production scripts #178

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sankalpmukim wants to merge 13 commits into
base: main
Choose a base branch
from
Open

Add standalone self-host output and align init production scripts #178

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
17a416e
feat: add standalone self-host output for vinext build
Feb 27, 2026
09c9a2c
Merge main into feat/selfhost-standalone-build-start, resolve conflicts
james-elicx Mar 28, 2026
b8c22d4
fmt
james-elicx Mar 28, 2026
d9d676b
Address bonk review: fix duplicate PHASE constant, complete lazy-chun…
james-elicx Mar 29, 2026
c6eba51
Address bonk nits: document regex patterns, move PHASE re-exports to …
james-elicx Mar 29, 2026
4f0a549
refactor(standalone): use Vite bundle graph for server externals inst…
james-elicx Mar 29, 2026
8dbc469
fix(standalone): copy vinext runtime deps, add node_modules filter to…
james-elicx Mar 29, 2026
15e8254
fix(standalone): address round-6 bonk nits — explicit root, manifest …
james-elicx Mar 29, 2026
2f8d0e8
fix(standalone): address round 7 bonk review comments
james-elicx Mar 29, 2026
242cc84
fix(standalone): address round 8 bonk review comments
james-elicx Mar 29, 2026
ab6e2a4
Merge remote-tracking branch 'origin/main' into feat/selfhost-standal…
james-elicx Mar 29, 2026
5bed771
interface -> type
james-elicx Mar 29, 2026
4656869
fix(standalone): address round 9 bonk review comments
james-elicx Mar 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 33 additions & 20 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,16 @@ Options: `-p / --port <port>`, `-H / --hostname <host>`, `--turbopack` (accepted

`vinext init` options: `--port <port>` (default: 3001), `--skip-check`, `--force`.

If your `next.config.*` sets `output: "standalone"`, `vinext build` emits a self-hosting bundle at `dist/standalone/`. Start it with:

```bash
Copy link
Copy Markdown
Contributor

@ask-bonk ask-bonk bot Mar 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider adding a note that standalone mode uses HOST (not HOSTNAME) for the bind address. Users migrating from Next.js standalone may have HOSTNAME configured in their deployment environments, and the behavioral difference would be confusing without documentation.

Something like:

Environment variables: `PORT` (default 3000), `HOST` (default 0.0.0.0).
Note: Next.js standalone uses `HOSTNAME`, but vinext uses `HOST` to avoid
collision with the system-set HOSTNAME variable on Linux.

node dist/standalone/server.js
```

Environment variables: `PORT` (default `3000`), `HOST` (default `0.0.0.0`).

> **Note:** Next.js standalone uses `HOSTNAME` for the bind address, but vinext uses `HOST` to avoid collision with the system-set `HOSTNAME` variable on Linux. Update your deployment config accordingly.

### Starting a new vinext project

Run `npm create next-app@latest` to create a new Next.js project, and then follow these instructions to migrate it to vinext.
Expand All @@ -94,7 +104,7 @@ This will:
2. Install `vite`, `@vitejs/plugin-react`, and App Router-only deps (`@vitejs/plugin-rsc`, `react-server-dom-webpack`) as devDependencies
3. Rename CJS config files (e.g. `postcss.config.js` -> `.cjs`) to avoid ESM conflicts
4. Add `"type": "module"` to `package.json`
5. Add `dev:vinext` and `build:vinext` scripts to `package.json`
5. Add `dev:vinext`, `build:vinext`, and `start:vinext` scripts to `package.json`
6. Generate a minimal `vite.config.ts`

The migration is non-destructive -- your existing Next.js setup continues to work alongside vinext. It does not modify `next.config`, `tsconfig.json`, or any source files, and it does not remove Next.js dependencies.
Expand All @@ -103,6 +113,8 @@ vinext targets Vite 8, which defaults to Rolldown, Oxc, Lightning CSS, and a new

```bash
npm run dev:vinext # Start the vinext dev server (port 3001)
npm run build:vinext # Build production output with vinext
npm run start:vinext # Start vinext production server
npm run dev # Still runs Next.js as before
```

Expand Down Expand Up @@ -458,25 +470,26 @@ Every `next/*` import is shimmed to a Vite-compatible implementation.

### Server features

| Feature | | Notes |
| ---------------------------------- | --- | ------------------------------------------------------------------------------------------- |
| SSR (Pages Router) | ✅ | Streaming, `_app`/`_document`, `__NEXT_DATA__`, hydration |
| SSR (App Router) | ✅ | RSC pipeline, nested layouts, streaming, nav context for client components |
| `getStaticProps` | ✅ | Props, redirect, notFound, revalidate |
| `getStaticPaths` | ✅ | `fallback: false`, `true`, `"blocking"` |
| `getServerSideProps` | ✅ | Full context including locale |
| ISR | ✅ | Stale-while-revalidate, pluggable `CacheHandler`, background regeneration |
| Server Actions (`"use server"`) | ✅ | Action execution, FormData, re-render after mutation, `redirect()` in actions |
| React Server Components | ✅ | Via `@vitejs/plugin-rsc`. `"use client"` boundaries work correctly |
| Streaming SSR | ✅ | Both routers |
| Metadata API | ✅ | `metadata`, `generateMetadata`, `viewport`, `generateViewport`, title templates |
| `generateStaticParams` | ✅ | With `dynamicParams` enforcement |
| Metadata file routes | ✅ | sitemap.xml, robots.txt, manifest, favicon, OG images (static + dynamic) |
| Static export (`output: 'export'`) | ✅ | Generates static HTML/JSON for all routes |
| `connection()` | ✅ | Forces dynamic rendering |
| `"use cache"` directive | ✅ | File-level and function-level. `cacheLife()` profiles, `cacheTag()`, stale-while-revalidate |
| `instrumentation.ts` | ✅ | `register()` and `onRequestError()` callbacks |
| Route segment config | 🟡 | `revalidate`, `dynamic`, `dynamicParams`. `runtime` and `preferredRegion` are ignored |
| Feature | | Notes |
| ------------------------------------------ | --- | ------------------------------------------------------------------------------------------- |
| SSR (Pages Router) | ✅ | Streaming, `_app`/`_document`, `__NEXT_DATA__`, hydration |
| SSR (App Router) | ✅ | RSC pipeline, nested layouts, streaming, nav context for client components |
| `getStaticProps` | ✅ | Props, redirect, notFound, revalidate |
| `getStaticPaths` | ✅ | `fallback: false`, `true`, `"blocking"` |
| `getServerSideProps` | ✅ | Full context including locale |
| ISR | ✅ | Stale-while-revalidate, pluggable `CacheHandler`, background regeneration |
| Server Actions (`"use server"`) | ✅ | Action execution, FormData, re-render after mutation, `redirect()` in actions |
| React Server Components | ✅ | Via `@vitejs/plugin-rsc`. `"use client"` boundaries work correctly |
| Streaming SSR | ✅ | Both routers |
| Metadata API | ✅ | `metadata`, `generateMetadata`, `viewport`, `generateViewport`, title templates |
| `generateStaticParams` | ✅ | With `dynamicParams` enforcement |
| Metadata file routes | ✅ | sitemap.xml, robots.txt, manifest, favicon, OG images (static + dynamic) |
| Static export (`output: 'export'`) | ✅ | Generates static HTML/JSON for all routes |
| Standalone output (`output: 'standalone'`) | ✅ | Generates `dist/standalone` with `server.js`, build artifacts, and runtime deps |
| `connection()` | ✅ | Forces dynamic rendering |
| `"use cache"` directive | ✅ | File-level and function-level. `cacheLife()` profiles, `cacheTag()`, stale-while-revalidate |
| `instrumentation.ts` | ✅ | `register()` and `onRequestError()` callbacks |
| Route segment config | 🟡 | `revalidate`, `dynamic`, `dynamicParams`. `runtime` and `preferredRegion` are ignored |

### Configuration

Expand Down
Loading
Loading