Internals

Create App

The create/ folder is a small standalone package that scaffolds a fresh Bascik project. It is separate from the main package because it is meant to be run as a user-facing CLI, not as a workspace dependency.

Why it is separate

The repo root uses Yarn workspaces. The package code lives in pkg/, while the scaffold lives in create/ and is installed like a normal Node tool.

That split keeps the monorepo dev flow simple and keeps the generated project familiar for normal users.

Code structure

The package has two source files with distinct responsibilities:

  • create/src/scaffold.ts — pure data and file-writing logic. All generated file content lives here as exported string constants and functions. No I/O beyond fs/promises. This is what the tests cover.
  • create/src/index.ts — the CLI entry point. Handles prompts, the -y flag, and spawns npm install / npm run dev. Not unit-tested.

Keeping them split means you can test every generated file without invoking the CLI or touching the filesystem.

What the CLI generates

Running npx create-bascik <name> writes this structure:

text
<name>/
  package.json
  bascik.config.js
  .gitignore
  src/
    pages/
      index.html
      about.html
      contact.html
      404.html
      css/
        styles.css
    components/
      site-meta/
        site-meta.html
      site-header/
        site-header.html
        site-header.css
      site-footer/
        site-footer.html
        site-footer.css
      feat-card/
        feat-card.html
        feat-card.css
      my-counter/
        my-counter.html
        my-counter.css

The feat-card component demonstrates named slots. The my-counter component demonstrates scoped JS with two independent instances on the home page.

After scaffolding, the CLI offers to run npm install and npm run dev. Both prompts can be skipped with -y.

Why the generated app uses npm

The scaffold runs npm install and npm run dev so users do not need Yarn to get started. The repo itself uses Yarn workspaces for contributor work, but the generated site is designed to feel like a regular app from a standard Node CLI.

Modifying the scaffold

All generated file content is defined as string constants in scaffold.ts. To change what a new project looks like, edit the relevant constant there. After any change, rebuild before testing:

sh
cd create
npm run build

The npm link symlink points at the create/ directory, so a fresh dist/ is picked up immediately without relinking.

Tests

The scaffold is fully unit-tested. Run the tests from the create/ directory:

sh
cd create
npm test

Tests mock fs/promises and verify that every expected file is written with the right content. If you add or rename a generated file, add a corresponding test case in scaffold.test.ts.

Lockfiles and package managers

Contributors use Yarn at the monorepo root with a single yarn.lock.

Generated projects intentionally use npm, and each generated project gets its own package-lock.json.

Testing create app locally

1. Install the repo

From the repo root:

sh
yarn install

2. Link the local scaffold

sh
cd create && npm install && npm link && cd ..

3. Create a test site

sh
npx create-bascik my-site -y

The -y flag skips both prompts. The npm install will print a 404 error for @bascik/bascik (not on npm yet), but the dev server starts anyway — the workspace node_modules symlink resolves the package. Command+Click the URL to open it in a browser.

text
Server running at https://localhost:8443

Cleanup after local testing

Once you are done, unlink to return to the normal published package flow.

From the repo root:

sh
cd create
npm unlink

If you are still actively iterating on the generator, leaving it linked is fine.