eddev CLI

The eddev CLI is the main development and build runner for an eddev theme. Run it from the theme root, usually through the project scripts in package.json.

{
  "scripts": {
    "dev": "eddev dev",
    "build": "eddev build"
  }
}

Most day-to-day work should use yarn dev --fast. Fast mode runs the local serverless dev server with hot reloading on port 8080, plus GraphQL codegen. It skips the admin and frontend SPA bundles, which are only needed when you access the local WordPress frontend directly without the :8080 dev server port.

Production SPA builds use yarn build. To check serverless production behavior locally, run eddev build --serverless and then eddev preview.

The CLI reads .env, ed.config.json, the Git repo name, WordPress theme files, GraphQL files, and the WordPress origin. If a command behaves strangely, first check that you are running it from the theme root and that SITE_URL points to the WordPress origin.

Commands

Command	What It Does
`eddev dev --fast`	Recommended development command. Starts GraphQL codegen and the hot-reloading serverless dev server on port `8080`.
`eddev dev`	Starts every dev mode, including watched admin and frontend SPA bundles. Use this when you need the WordPress-hosted SPA/admin asset builds.
`eddev build`	Builds production frontend and admin bundles for WordPress-hosted SPA mode. This is not the serverless build.
`eddev build --serverless`	Builds the production serverless app. Usually followed by `eddev preview` when testing locally. Vercel uses this path automatically because `VERCEL` is set in the environment.
`eddev preview`	Runs the output from a previous `eddev build --serverless`. Usually used together with that build command.
`eddev analyze`	Generates a frontend bundle analysis in `dist/frontend-analysis/`.
`eddev info`	Prints discovered project, block, and view information.

Some older theme package.json files may still include eddev setup. That command is not present in the current CLI source; prefer the active commands above.

`eddev dev`

Use fast mode for normal development:

yarn dev --fast

Fast mode runs:

Mode	What It Does
`serverless`	Starts the local serverless dev server on port `8080`. This is the normal local frontend preview, with hot reloading.
`graphql`	Loads the WordPress schema, validates project GraphQL files, generates TypeScript outputs, and optimizes query files for PHP.

The full eddev dev command runs every mode:

Mode	What It Does
`serverless`	Starts the local serverless dev server on port `8080`.
`graphql`	Runs GraphQL codegen and optimized query output.
`frontend`	Builds and watches the WordPress-hosted SPA frontend bundle.
`admin`	Builds and watches WordPress admin/editor assets.

Use the full command when you specifically need the local WordPress frontend or admin/editor asset bundles. If you are previewing the site through https://site.local:8080, fast mode is usually enough.

The terminal UI shows the serverless frontend URL, the WordPress origin URL, and the status of the active services. Press q to quit. Press c or k to clear the visible serverless log.

Dev Options

Option	What It Does
`--fast`	Recommended. Shorthand for `--mode graphql,serverless`. Runs the hot-reloading serverless dev server and GraphQL codegen only.
`--https <enabled>`	Enables or disables HTTPS for the serverless dev server. Defaults to `true`. Use `--https false` for plain HTTP.
`--verbose`	Shows extra debugging information in logs.

Examples:

yarn dev --fast
yarn dev --https false

--mode <modes> is available for debugging individual services, for example yarn dev --mode graphql or yarn dev --mode frontend,admin. Prefer --fast for normal project work.

When HTTPS is enabled, eddev creates a local certificate under .eddev/certs/. If macOS does not trust the certificate yet, the CLI prints Keychain instructions.

Generated Files

The CLI writes several generated files during dev and build.

Output	Source	Purpose
`ed.dist.json`	Blocks, views, template parts	PHP reads this manifest to register blocks, templates, and related theme metadata.
`types.graphql.ts`	WordPress schema and project GraphQL files	GraphQL operation, fragment, scalar, enum, and schema-derived TypeScript types.
`types.views.ts`	`views/*/.graphql` and view manifest	The `ViewProps` map used by `defineView`.
`types.blocks.ts`	`blocks/*/.graphql` and block manifest	The `BlockProps` map used by `defineBlock`.
`types.util.ts`	WordPress info, blocks, views	Utility global types for post types, page templates, core blocks, block tags, flags, and post meta.
`types.api.ts`	`server/routes/*/`	RPC route and context types used by serverless functions and RPC hooks.
`hooks/queries.ts`	`queries/*/.graphql`	Runtime query and mutation hooks.
`schema.json`	WordPress GraphQL schema	Local schema file for editor tooling.
`.eddev/queries/**`	Project GraphQL files	Optimized query text and fragments used by the PHP runtime.
`.eddev/dev` and `.eddev/prod`	Build codegen	Internal bootstrap files for SPA and serverless builds.

Do not edit generated files directly. Change the source block, view, route, or GraphQL file instead.

GraphQL Codegen

GraphQL codegen is part of eddev dev and eddev build; there is no separate public command for it.

The generator:

loads the GraphQL endpoint from DEBUG_GRAPHQL_URL
passes SITE_API_KEY when origin protection is enabled
reads GraphQL files from views/, blocks/, queries/, and queries/fragments/
validates operations against the WordPress schema
writes TypeScript types and generated hooks
writes optimized query files into .eddev/queries/

For file locations and caching comments such as # ttl: 300 and # nocache, see GraphQL.

`eddev build`

eddev build builds the production frontend and admin bundles used by WordPress-hosted SPA mode. It does not build the serverless app.

yarn build

This production build:

loads project configuration and manifests
writes ed.dist.json
generates SPA bootstrap files
builds the admin bundle into dist/cms/
builds the frontend bundle into dist/frontend/
runs GraphQL generation and writes optimized query files

Use this when deploying or pushing the theme to WordPress in SPA mode, including the WordPress admin/editor assets.

`eddev build --serverless`

eddev build --serverless builds the production serverless app. Use it with eddev preview to test how the site will behave on production Vercel.

eddev build --serverless
eddev preview

When Vercel runs the build, eddev takes the serverless path automatically because the VERCEL environment variable is set.

Serverless builds require SITE_URL so eddev knows which WordPress origin to query. If origin protection is enabled, also set SITE_API_KEY. Before building, the CLI checks that it can access the origin.

See Serverless for Vercel setup, SITE_URL, SITE_API_KEY, endpoint mappings, and cache behavior.

`eddev preview`

eddev preview runs the local production serverless build from .output/server/index.mjs. It is mainly useful after eddev build --serverless.

eddev preview
eddev preview --port 8081

eddev uses the SITE_URL hostname when it ends in .local; otherwise it falls back to 127.0.0.1. The command sets up local HTTPS with the same certificate helper used by eddev dev.

The current preview command exposes --host as a flag rather than a value-taking option, so prefer the default host behavior and only override --port.

Run eddev build --serverless before using eddev preview; either command on its own is rarely useful for day-to-day work.

`eddev analyze`

eddev analyze builds a frontend analysis bundle and writes a visualizer report under dist/frontend-analysis/.

eddev analyze

Use it when a client bundle looks too large or when you need to inspect what is included in the frontend build.

`eddev info`

eddev info prints the discovered project information, block manifest, and view manifest.

eddev info
eddev info --verbose

This is useful when WordPress is not registering an expected block or page template. It lets you check whether eddev can discover the source files before debugging PHP registration.

Environment Variables

Variable	Used By	Notes
`SITE_URL`	Project loading, serverless dev/build, preview	WordPress origin URL. Required for serverless work.
`SITE_API_KEY`	GraphQL, runtime query fetches, serverless origin requests	Optional unless the WordPress origin uses eddev Access Control.
`DEBUG_GRAPHQL_URL`	GraphQL codegen	WordPress/PHP normally writes this for local development. Refresh the WordPress admin if it is missing on a new site.

The CLI loads .env before it starts. Vercel project environment variables are used for production serverless builds.

Variables prefixed with ED_PUBLIC_ are injected into client and server bundles. Variables prefixed with ED_ are injected only into non-client bundles.

eddev CLI

On this page