Scaffold Options

For an interactive first project, follow Getting Started. To create a project from a script, pass the directory and --yes:

npm create gtkx@beta -- my-app --yes --application-id com.example.MyApp \
    --display-name "My App"

Options

Option	Default without prompts
<directory>	Required. A name or a path, such as apps/my-app or ~/Projects/my-app.
--application-id	Derived from the directory: my-app gets com.myapp.app.
--display-name	Derived from the directory: my-app gets My App.
-p, --package-manager	pnpm, npm or yarn. Detected from a packageManager field or lockfile in the current directory or a parent, then from the command running the scaffold, otherwise pnpm.
--no-typescript	TypeScript. Pass it for a JavaScript project.
--no-vitest	The Vitest setup is included. Pass it to leave it out.
-y, --yes	Prompts for every option not passed. Without a terminal, as in CI, the command never prompts.
-f, --overwrite	Refuses a directory that is not empty. See Existing directories.
--skip-install	Installs dependencies. With it, run your package manager's install command in the project afterward.

The package name is the directory name when that is a valid npm package name. Otherwise the scaffold lowercases it, removes accents and replaces other characters with hyphens, so Unit Converter becomes unit-converter and café becomes cafe. --no-interactive is the same as --yes, and --typescript and --vitest request the defaults explicitly. npm create gtkx@beta -- --help prints every option.

The new project depends on the major versions this GTKX release supports, not the newest ones: React, @types/react and Vitest within the ranges GTKX declares as peers, the Vite range @gtkx/cli depends on, TypeScript 6, and the @types/node major of the oldest Node.js GTKX supports. When a later GTKX release supports a new major, run gtkx upgrade first, then move those packages with your package manager.

With Yarn 2 or newer, the new package.json pins the installing Yarn release in its packageManager field, as yarn init -2 does, so Corepack runs that release on every machine. The installing release is the Yarn running the scaffold, as with corepack yarn@4 create gtkx@beta, otherwise the one Corepack runs in the target directory. An app inside a Yarn workspace gets no pin; the workspace root owns it.

Existing directories

Without prompts, a directory that holds anything other than .git stops the command before it changes anything, and the error lists the scaffold files it would replace. --overwrite replaces those files and leaves every other file in place. Interactive runs ask before replacing them. The command refuses a destination reached through a symbolic link.

The package manager's own settings are added to rather than replaced. An existing .yarnrc.yml keeps its registry, authentication and other settings and gains nodeLinker: node-modules and the release-age exemptions. An existing pnpm-workspace.yaml keeps its settings and packages and gains allowBuilds entries for the scaffold's native dependencies and the exemptions. An existing .npmrc keeps its lines and gains the exemptions at the end. A packageManager field naming the chosen package manager stays in the new package.json, so the project keeps its pinned version.

The scaffold initializes a Git repository with an initial commit only in a new or empty directory outside an existing repository.

Release-age gates

Package managers can hold back versions published more recently than a set age. Yarn 4.15 and newer (npmMinimalAgeGate) and pnpm 11 and newer (minimumReleaseAge) hold back packages published within the last day by default; npm's min-release-age applies only when set. So that a project created on the day of a GTKX release still installs it, the scaffold exempts GTKX's own packages, @gtkx/* and create-gtkx, which @gtkx/cli depends on, in the configuration it writes. Every other dependency keeps the gate.

.yarnrc.yml

npmPreapprovedPackages:
    - "@gtkx/*"
    - create-gtkx

pnpm-workspace.yaml

minimumReleaseAgeExclude:
    - "@gtkx/*"
    - create-gtkx

.npmrc

min-release-age-exclude[]=@gtkx/*
min-release-age-exclude[]=create-gtkx

Yarn releases before 4.10 refuse to run with a setting they do not know, so .yarnrc.yml gets npmPreapprovedPackages only when the project's Yarn is 4.10 or newer: the release its yarnPath or packageManager field selects, otherwise the Yarn running the scaffold. gtkx upgrade adds the same entries to a project that lacks them before it installs a new release.

Workspaces

Inside a workspace whose root lists the target directory, in the packages of pnpm-workspace.yaml for pnpm or the workspaces of the root package.json for npm and Yarn, the scaffold adds the app to that workspace:

pnpm create gtkx@beta apps/my-app

The app installs through the workspace and gets no lockfile or package manager configuration of its own, so pnpm add, gtkx upgrade and other commands run from the app act on the whole workspace. Its dependencies get their own version ranges rather than catalog: references, so a workspace catalog that pins another major version of react or vitest neither changes nor applies to the app.

The package managers read these settings only from the workspace root. The scaffold does not edit the root; when the root lacks an entry, the command prints it, and you add it and run the workspace's install command:

Package manager	Root settings the app needs
pnpm	allowBuilds for @swc/core and esbuild, and the minimumReleaseAgeExclude exemptions, in pnpm-workspace.yaml
npm	allowScripts for @swc/core and esbuild in package.json, and the min-release-age-exclude[] lines in .npmrc
Yarn	nodeLinker: node-modules and, with Yarn 4.10 or newer, the npmPreapprovedPackages exemptions in .yarnrc.yml; dependenciesMeta for @swc/core and esbuild in package.json

Until the root has them, pnpm skips the build scripts of @swc/core and esbuild, Yarn installs the workspace with Plug'n'Play, which GTKX does not support, and a release-age gate holds back a GTKX release published that day. When the install fails, the command prints the missing entries first; Troubleshooting covers recovery.

The app gets its own .mcp.json, and the scaffold also adds a server named gtkx to the .mcp.json at the workspace root, where AI clients are usually opened. That server starts the app's MCP server through the workspace's package manager:

Workspace	Command
pnpm	pnpm --dir apps/my-app exec gtkx mcp
npm	npm exec --no --workspace apps/my-app -- gtkx mcp
Yarn 2 or newer	yarn workspace my-app exec gtkx mcp
Yarn 1	yarn --silent --cwd apps/my-app gtkx mcp

Other servers in the file and its indentation stay. When the root .mcp.json already has a GTKX server, such as an earlier app's, the scaffold adds none, because one server drives every running GTKX app. When the file is not a valid MCP configuration, the scaffold leaves it unchanged and prints the entry to add.