Required dependencies

npm install react react-dom
npm install postcss
npm install next

If you are running the source build pipeline directly (taskfile, swc compilation), you also need the native SWC binaries that match your platform. These ship as optional dependencies of next (e.g. @next/swc-linux-x64-gnu). Run npm install next --ignore-scripts only if you want to skip native compilation; otherwise let the default install resolve the correct binary automatically.

Project setup

1. Copy the source/ directory into your repository, e.g. ./packages/next/.
2. In your root package.json, add a workspace entry (if using npm/yarn workspaces):

   {
     "workspaces": ["packages/next"]
   }
   

3. Add path aliases in tsconfig.json so your application can resolve the package as nextjs-project:

   {
     "compilerOptions": {
       "paths": {
         "nextjs-project": ["./packages/next/index.d.ts"],
         "nextjs-project/*": ["./packages/next/*"]
       }
     }
   }
   

4. If you need the Babel preset, add source/babel.js as a preset in babel.config.js:

   module.exports = { presets: ['./packages/next/babel.js'] }
   

5. Set required environment variables before starting your server:

   NODE_ENV=production          # or development
   NEXT_TELEMETRY_DISABLED=1    # opt out of telemetry during dev
   

6. For CSS minification via the bundled cssnano-simple, require it directly:

   const cssnanoSimple = require('./packages/next/src/bundles/cssnano-simple/index.js')
   

Public API

cssnanoSimple (CSS minification)

import postcss from 'postcss'

const cssnanoSimple: (
  opts?: {
    excludeAll?: boolean
    [pluginName: string]: boolean | { exclude?: boolean } | undefined
  },
  postcss?: typeof import('postcss')
) => postcss.Plugin

A lightweight PostCSS plugin factory. Use it when you need deterministic, fast CSS minification in a custom build pipeline. Pass excludeAll: true to start with all sub-plugins disabled and opt individual ones back in.

pluginCreator (PostCSS stub plugin)

interface PostCSSPlugin {
  postcssPlugin: string
  prepare(): Record<string, never>
}

declare function pluginCreator(): PostCSSPlugin
pluginCreator.postcss: true

A no-op PostCSS plugin stub used internally to replace postcss-svgo when building cssnano-preset-simple. Reference it when you need to neutralize a PostCSS plugin without removing it from the pipeline.

Client hydration runtime (src/client/index.tsx)

// Internal API - consumed via the built client bundle
import type { NextWebVitalsMetric, NEXT_DATA } from './shared/lib/utils'
import type Router from './shared/lib/router/router'
import type { AppComponent, AppProps, PrivateRouteInfo } from './shared/lib/router/router'

The client hydration entry wires React, the Pages Router, head management, image config, and App Router adapters into the browser. Use it as a reference when implementing a custom client bootstrap or patching hydration behavior.

Working examples

Scenario - CSS minification in a custom build script

A build script that reads raw CSS and outputs a minified version using the bundled cssnano-simple without pulling in the full cssnano package.

import postcss from 'postcss'
// Require the bundled implementation directly
const cssnanoSimple = require('./packages/next/src/bundles/cssnano-simple/index.js')

async function minifyCSS(rawCSS: string, filePath: string): Promise<string> {
  const plugin = cssnanoSimple({ excludeAll: false }, postcss)
  const result = await postcss([plugin]).process(rawCSS, { from: filePath })
  return result.css
}

minifyCSS('body { color: red;   margin:  0 }', 'styles.css').then(console.log)
// → body{color:red;margin:0}

Scenario - Registering a no-op PostCSS stub for a disabled plugin

When assembling a custom PostCSS pipeline and you want to include a plugin slot that does nothing (useful for conditional pipelines in tests or CI).

const pluginCreator =
  require('./packages/next/src/bundles/postcss-plugin-stub/index.js')

import postcss from 'postcss'

async function processWithStub(css: string): Promise<string> {
  // pluginCreator is a valid postcss plugin; it performs no transforms
  const result = await postcss([pluginCreator()]).process(css, { from: undefined })
  return result.css
}

processWithStub('h1 { font-size: 2rem }').then(console.log)
// → h1 { font-size: 2rem }  (unchanged)

Scenario - Selective cssnano plugin activation with excludeAll

Enable only specific cssnano sub-plugins to avoid undesirable transforms (e.g. keep calc() intact while still deduplicating rules).

const cssnanoSimple = require('./packages/next/src/bundles/cssnano-simple/index.js')
import postcss from 'postcss'

async function minifySafe(css: string): Promise<string> {
  // Start with everything excluded, then opt specific plugins back in
  const plugin = cssnanoSimple(
    {
      excludeAll: true,
      // re-enable only deduplicate rules
      rawCache: false,
    },
    postcss
  )
  const result = await postcss([plugin]).process(css, { from: undefined })
  return result.css
}

File walkthrough

• .storybook/ - Storybook main config, preview body HTML, preview entry, and test-runner setup for component-level visual tests.
• compat/ - Re-exports of older router APIs (compat/router) that maintain backwards compatibility for consumers on prior major versions.
• experimental/ - Feature-flagged modules not covered by semantic versioning; import at your own risk.
• font/ - font/google/index.js and font/local/index.js implement font optimization, subsetting, and CSS variable injection.
• image-types/ - Ambient .d.ts files describing image import shapes for TypeScript consumers.
• legacy/ - Shims for APIs removed from the public surface but still needed by some downstream packages.
• navigation-types/ - TypeScript declarations for useRouter, usePathname, useSearchParams, and related App Router hooks.
• src/ - Core source tree: src/client/ (browser runtime), src/server/ (Node.js server), src/build/ (webpack/SWC pipeline), src/shared/ (isomorphic utilities), and src/bundles/ (vendored deps like cssnano-simple).
• types/ - Top-level ambient declarations supplementing the per-entry .d.ts files.
• webpack-plugins/ - Custom webpack plugins invoked during next build (e.g. font optimization, telemetry).
• taskfile.js / taskfile-*.js - Task runner scripts for compiling the framework itself via ncc, SWC, or webpack; not needed at runtime.
• errors.json - Machine-readable map of error codes to documentation URLs; consumed by the error overlay.
• tsconfig.json / tsconfig.build.json - TypeScript project references; tsconfig.build.json is used for production compilation.

Common pitfalls and fixes

• SWC binary mismatch: Native .node files for @next/swc-* must match the exact next version; fix by running npm install next@<exact-version> and letting postinstall download the correct binary.
• ESM/CJS interop in cssnano-simple: The bundled cssnano-simple exports a CommonJS function; use require() or set "esModuleInterop": true in tsconfig.json with a default import.
• PostCSS version pin: cssnano-simple imports postcss as a peer; pin to user@example.com because the plugin API changed incompatibly between v7 and v8.
• NEXT_TELEMETRY_DISABLED missing: Without this env var, the build pipeline attempts network calls during development; set it to 1 in .env.local to prevent unexpected outbound traffic.
• src/client/index.tsx is not a public entry point: Do not import it directly in application code; it is the internal hydration bootstrap and assumes a specific Webpack chunk graph produced by next build.
• TypeScript path aliases must include /* variants: A paths entry for nextjs-project without a matching nextjs-project/* entry will cause TS2307 errors for sub-path imports like nextjs-project/server.

Vibe-coding prompt template

I have added the Next.js framework source to my project under `./packages/next/`
and have a `USAGE.md` describing its structure and API.

Upstream package name: user@example.com

Please help me integrate it step by step:

1. Read `USAGE.md` and `source/` to understand what is available.
2. Update `tsconfig.json` to add path aliases for `nextjs-project` and `nextjs-project/*`
   pointing at `./packages/next/`.
3. Wire `source/src/bundles/cssnano-simple/index.js` into my existing PostCSS pipeline
   in `build/css.ts`, replacing the current `cssnano` dependency.
4. Add a `minifyCSS(input: string): Promise<string>` utility that uses the bundled
   cssnano-simple with the options I specify.
5. Show me how to run the internal taskfile build (`taskfile.js`) to recompile
   the package after I modify source files.
6. Point out any peer dependency version conflicts between my current `package.json`
   and what `source/` requires, and suggest pinned versions.

Constraints: do not invent APIs not present in `USAGE.md` or `source/`.
Keep all imports relative to `./packages/next/` or using the `nextjs-project` alias.

License and credit

Next.js is released under the MIT License. See source/license.md for the full text. The upstream project is maintained by Vercel at https://github.com/vercel/next.js and published to npm as next. The vendored cssnano-simple implementation originates from https://github.com/Timer/cssnano-simple, also MIT licensed.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.