create-bascik

Interactive project initializer for Bascik: the command behind npm create bascik. Use it to start a new Bascik site with a working starter, editor settings, tests, and the agent skills. Requires Node.js 24.21 or newer. The Getting Started guide walks through the result, and Create App internals explains how the scaffolder works.

Quick Start

Scaffold a new Bascik project in one command:

npm create bascik my-site -y

Pass a project name as an argument or run without arguments to be prompted:

npm create bascik

The name is a new folder under the current one, such as my-site or sites/my-site; ., .., absolute paths and spaces are refused. A folder that already has one of the starter's files, such as package.json or src/pages/index.html, is refused before anything is written. To add Bascik to an existing project, see Manual Setup.

What it scaffolds

create-bascik creates a complete, ready-to-run starter site:

my-site/
├── AGENTS.md                       ← Project brief for coding assistants
├── CLAUDE.md                       ← Imports AGENTS.md for Claude Code
├── .agents/skills/                 ← Bascik agent skills for Copilot, Cursor, Codex, and others (on Y)
├── .claude/skills/                 ← The same skills for Claude Code (on Y)
├── .vscode/
│   ├── launch.json                 ← Debug launchers for dev server and tests
│   ├── extensions.json             ← Recommends official Bascik extension
│   └── settings.json               ← Stops false VS Code errors on pages with several scripts
├── src/
│   ├── components/                 ← site-meta, site-header, site-footer, feature-card, my-counter, contact-form
│   └── pages/                      ← index.html, about.html, contact.html, 404.html, css/styles.css
├── package.json                    ← dev, build, lint, test, and e2e scripts
└── .gitignore

The starter does not include bascik.config.ts because it uses Bascik's built-in defaults. Add a config only when the project needs non-default behavior.

Agent skills

After scaffolding, create-bascik asks:

Install the Bascik agent skills for coding assistants (Claude Code, Copilot, Cursor, Codex...)? (Y/n)

Yes, the default and what -y answers, runs the skills CLI to install every Bascik skill except the opt-in bascik-refactor, at the release tag matching the Bascik version scaffolded. --no-skills skips it. When you skip it, or the install fails, for example offline, the project is still created and the command to run later is printed, pinned to the same release tag.

| Flag | Effect | | :------------- | :------------------------------------------------- | | -y, --yes | Answer every question with its default | | --no-skills | Do not install the agent skills | | --no-install | Do not run npm install, nor start the dev server | | --no-dev | Do not start the dev server |

After scaffolding:

cd my-site
npm run dev

Your site will be live at http://localhost:8080 in every template. npm run dev is always the Bascik dev server; the Cloudflare and Netlify templates add npm run dev:cloudflare (http://127.0.0.1:8787) and npm run dev:netlify (http://127.0.0.1:8888) to run the same site in the host's local runtime.

Templates

Pick a starter with --template <name> (or --template=<name>). Without the flag you get the default starter; the prompts never ask where the site will be deployed, and an adapter can be added to any project later.

| Template | What you get | | :----------- | :----------------------------------------------------------------------------------------------------------------------- | | default | The static starter above. static is accepted as an alias. | | cloudflare | The same starter plus the Cloudflare adapter, Wrangler, and an edge demo. | | netlify | The same starter plus the Netlify adapter, a netlify.toml, and the edge demo. |

npm create bascik my-site -- --template cloudflare

The -- matters: npm keeps flags placed before it for itself and does not pass them on, so --template has to follow a --. -y is the exception, since create-bascik also reads npm's own yes setting (npm create bascik my-site -y -- --template cloudflare skips every prompt).

The Cloudflare template differs from the default in these files only:

• package.json: @bascik/adapter-cloudflare and wrangler as dev dependencies; dev stays bascik, and dev:cloudflare runs bascik --target cloudflare with source watching and browser live reload in the real local platform runtime; build runs bascik --build --target cloudflare; preview and deploy run Wrangler from the emitted dist/.bascik/cloudflare/ folder.
• src/pages/edge.html: a page with a data-bascik-server script that the Worker renders on every request, linked from a fourth feature card on the home page.
• src/api/hello.ts: an API route served at /api/hello.
• e2e/app.spec.ts: one extra test covering the edge page.
• .gitignore: ignores .wrangler/.

After scaffolding a Cloudflare project:

npm run dev              # Bascik dev server on http://localhost:8080
npm run dev:cloudflare   # watched workerd development on http://127.0.0.1:8787
npm run build     # bascik --build --target cloudflare
npm run preview   # run the bundle locally in workerd
npm run deploy    # wrangler deploy

The Netlify template differs from the default in these files only:

• package.json: @bascik/adapter-netlify and netlify-cli as dev dependencies; dev stays bascik, and dev:netlify runs bascik --target netlify with source watching and browser live reload through the locally installed Netlify Dev; build runs bascik --build --target netlify && bascik-netlify-install; preview and deploy run the Netlify CLI through npx.
• netlify.toml: builds with npm run build, publishes publish/, and uses Netlify's URL as the site URL unless BASCIK_SITE_URL is set.
• src/pages/edge.html and src/api/hello.ts: the edge demo and API route, run in the Netlify Function.
• e2e/app.spec.ts: one extra test covering the edge page.
• .gitignore: ignores publish/ and .netlify/.

After scaffolding a Netlify project:

npm run dev           # Bascik dev server on http://localhost:8080
npm run dev:netlify   # watched Netlify development on http://127.0.0.1:8888
npm run build     # bascik --build --target netlify && bascik-netlify-install
npm run preview   # netlify dev --dir publish
npm run deploy    # netlify deploy --build --prod

Both adapter development workflows use a local HTTP-only proxy; --port and --host override its public address. A rebuild or failed build may return 503, but the watcher stays alive and retries after the next source edit. Live reload is injected only by that proxy, never into production artifacts. preview remains a production-output workflow without Bascik's source watcher, and bare bascik remains the Node development server.

Development & Testing

From the repository root:

yarn create:build      # compile build output
yarn create:typecheck  # TypeScript type check
yarn create:unit       # run unit tests
yarn create:coverage   # run unit tests with coverage report

The integration tests compile scaffolded projects with the built framework and Cloudflare adapter, so run yarn pkg:build && yarn adapter:cf:build first (CI does the same).