0002: Scaffold with init and npm create

Context#

A tool that needs “only Markdown and one config file” still has a first five minutes: a config with the right import, a project folder with a _project.yml, one record that shows the format, npm scripts, a .gitignore, and a CI workflow so the site is published from day one. Writing these by hand from the README is slow and error-prone, and a decision log often starts inside an existing repository that already has a package.json.

Decision#

inkan init [dir] copies a starter repository from the package and wires up package.json. It never overwrites a file that already exists, so it is safe to run inside an existing repository. npm create @tilaven/inkan is a thin wrapper, published as create-inkan, that runs the same init in a new folder.

The starter is complete: it builds and deploys without edits. Everything in it is a plain file you can change or delete afterwards.

How to use it#

A new repository#

1
npm create @tilaven/inkan@latest my-decisions
2
cd my-decisions
3
npm install
4
npm run dev

npm create @tilaven/inkan [dir] resolves the @tilaven/inkan package it depends on and runs inkan init <dir>. When you give no folder name it uses decisions-site. After init you still run npm install yourself; the output ends with the exact next commands.

An existing repository#

1
npm install -D @tilaven/inkan
2
npx inkan init

Without an argument init targets the current folder (or --root). With npx inkan init docs the files land in docs/, which is how this site is laid out. Run the CLI from that folder afterwards, or pass --root docs.

What init creates#

The dotfiles are stored in the package as _gitignore and _dockerignore and renamed on copy, because npm drops .gitignore from published packages. init prints every file it added with a + and marks package.json with ~.

How package.json is handled#

If there is no package.json, init creates one:

1
{
2
  "name": "my-decisions",
3
  "private": true,
4
  "type": "module",
5
  "scripts": {
6
    "dev": "inkan dev",
7
    "build": "inkan build",
8
    "preview": "inkan preview",
9
    "new": "inkan new"
10
  },
11
  "devDependencies": {
12
    "@tilaven/inkan": "^0.1.0"
13
  }
14
}

If one exists, init only adds to it:

• The four scripts are added. Scripts you already have, including ones with the same names, are kept as they are.
• "type": "module" is set only when type is missing. The config file is an ES module, so a repository that uses CommonJS keeps .ts for the config and is otherwise unaffected.
• @tilaven/inkan is added to devDependencies at the installed version, unless it is already in dependencies.

Nothing else in the file is touched, and key order of your existing fields is preserved.

Existing files are never replaced#

init skips any file that already exists at the destination and keeps going. Running it twice is harmless. This also means a second init does not refresh an old workflow file: delete it first if you want the current one.

After init#

1. Set title, url and repo in inkan.config.ts. repo enables the edit and “New ADR” buttons; url is used in feeds and llms.txt.
2. Rename the platform folder or add your own projects. A folder with records is enough; _project.yml adds the display name.
3. Push. The GitHub workflow needs Pages set to “GitHub Actions” as the source; the GitLab pipeline publishes to Pages on the default branch. Both set BASE_PATH=/<repository name> for project pages; remove that line for a custom domain. See GitHub and GitLab Pages.
4. Optional: docker build -t decisions . for a self-hosted image. See Docker and nginx.

Consequences#

• One command gives a repository that builds and deploys. New users see a working site before reading any documentation.
• Safe in existing repositories: nothing is overwritten and package.json is extended, not replaced.
• The starter is a snapshot. Files it created are yours from then on; updates to the package’s starter do not propagate to them, which is intended for CI files you will edit anyway.
• npm create @tilaven/inkan pins the @tilaven/inkan version it was published with. Use @latest to get the current one.
• The starter ships files for every target (GitHub, GitLab, Docker). Delete the ones you do not use.