gesso create

Create a standalone Next.js App Router prototype with Gesso already wired.

Syntax

The target directory is required at runtime:

pnpm dlx @acromedia/gesso-cli create <dir>

If the CLI is already installed in the current project:

pnpm gesso create <dir>

For example:

pnpm dlx @acromedia/gesso-cli create my-prototype

This is different from pnpm create @acromedia/gesso: gesso create produces a focused, standalone prototype rather than the prompted full integration starter.

Generated prototype

The prototype includes a Next.js App Router application, a Gesso theme, a client providers boundary with ThemeProvider and CssBaseline, and agent instruction files. The command attempts to install the gesso-react skill in each supported skill directory and reports each outcome.

Its package.json pins @acromedia/gesso exactly to the version targeted by the CLI's bundled catalog documentation and pins @acromedia/gesso-cli exactly to the running CLI version. Other framework and tool dependencies use the versions declared by the bundled prototype.

Target safeguards

The target must be absent or an empty directory inside an existing parent directory. The command refuses to overwrite a file or nonempty directory. It also rejects tilde paths and protects the current directory, its ancestors, the filesystem root, and the home directory from replacement.

Concurrent creates for the same target use an ownership lock. If a command reports a stale lock, first confirm that no other gesso create process is using the target, then follow the removal path printed by the command. Filesystem, bundled-template, or skill-installation failures include recovery guidance. One failed skill path does not fail the command when another path installs the skill or is safely skipped; only failure in every supported skill directory makes the command fail. That all-directory failure occurs after publication, so it can leave the usable prototype in place while asking you to repair the skill separately.

Authentication and next steps

Set up registry authentication before the one-shot invocation. Authentication from a project .npmrc where the command was launched is not copied to the new target; pnpm install in the generated project must be able to use home or target-local configuration.

On success, follow the printed paths and commands:

cd my-prototype
pnpm install
pnpm dev

Then run pnpm gesso agent from the prototype before writing code.