esa-pcg-cli

CLI for building Next.js, Astro and Nuxt projects into the artifact contract consumed by the PCG cloud-build pipeline.

Install

npm install --save-dev esa-pcg-cli

Build

The pipeline can pass its detected framework explicitly. Omitting --framework keeps the 0.1.17-compatible default of nextjs:

npx pcg build --framework nextjs --dir . --out-dir .pcg/output
npx pcg build --framework astro  --dir . --out-dir .pcg/output
npx pcg build --framework nuxt   --dir . --out-dir .pcg/output

PCG runs the framework build once and publishes exactly these directories after the complete result has passed validation:

.pcg/output/
├── assets/       # upload to CDN with relative paths unchanged
├── fc/           # zip the contents; EFC starts with `node start.mjs`
└── isr-cache/    # upload seeded cache bodies; empty for Astro and Nuxt

There is no manifest.json, framework/, or conf.jsonc. The fixed runtime contract is node start.mjs, process.env.PORT || 3000, and host 0.0.0.0.

Relative --out-dir values are resolved from --dir. The default is .pcg/output.

Local preview

npx pcg serve --dir . --port 3000

pcg serve starts the same fc/start.mjs that EFC executes.

Next.js integration

Next.js builds run through OpenNext with PCG's wrapper, converter, incremental-cache, and tag-cache overrides. The unified result contains CDN assets, the complete OpenNext server-functions/ tree (with default as the FC entrypoint), and build-time ISR/fetch cache bodies with OpenNext's internal build-id layer removed.

Existing user open-next.config.ts / .js files are preserved. When no config exists, PCG generates the same official Node converter and local ISR queue contract as [email protected].

revalidateTag and revalidatePath write the gateway tag store and also purge ESA CDN cache. PCG_CDN_PURGE_MODE=path (the default) uses the embedded OpenNext tag-to-path manifest and refreshes both route and /_next/data URLs; PCG_CDN_PURGE_MODE=tag sends cacheTags directly. The inbound request must carry host and x-er-origin-site-id, which the wrapper keeps in request-local context. Next.js 16 use cache is routed through the composable-cache handler.

Astro integration

Astro builds use the certified @astrojs/node standalone adapter. dist/client becomes the CDN asset payload, while the native dist/server + dist/client layout and traced runtime dependencies remain in fc/. Astro does not seed Route Cache during build, so isr-cache/ is empty.

Explicit Astro.cache.invalidate() / context.cache.invalidate() calls write the tag invalidation and call Gateway /cache/refresh with the current request's host and x-er-origin-site-id. Normal TTL/SWR expiry refreshes the runtime object and does not issue an extra purge request. For the injected PCG provider, the certified Astro 6/7 artifact patch preserves CDN-Cache-Control and Cache-Tag through the Node adapter so ESA can build and invalidate its L1 cache; user-provided cache providers are not patched.

PCG forces Astro's security.checkOrigin to false in EFC builds because EFC is a trusted origin reachable only through ESA, while ESA terminates TLS before forwarding over HTTP. Deployments that expose EFC directly must provide an equivalent CSRF boundary before using this artifact.

The temporary ESA-to-EFC diagnostic build appends requests whose pathname ends in /invalidate as NDJSON to /tmp/pcg-astro-request-headers.ndjson without requiring an enable flag. Other requests are not logged. Each record includes the complete normalized headers object and Node.js rawHeaders array. Override the path with PCG_ASTRO_REQUEST_HEADER_LOG_PATH. Because the log can contain Cookie, Authorization, and other credentials, delete it and remove this temporary diagnostic code immediately after diagnosis.

Nuxt integration

Nuxt builds use the bundled esa-nitro-preset, which extends Nitro's node-server preset and stores runtime cache entries through the signed PCG gateway client. The resulting fc/server bundle is supported by pcg serve; Nuxt does not seed isr-cache/ during build.

Other commands

deploy, upload-cache, and upload-assets remain legacy/manual commands. The cloud-build integration packages and uploads the unified build output itself.

License

MIT. See LICENSE.