Installation

This page shows how to make a new project with CAITS, how to add CAITS to a project, and how to update CAITS. One command makes the project. At the end, the project passes all its checks and starts.

What you need

Tool	Version
System	Linux, macOS, or WSL 2 on Windows. Native Windows does not work: CAITS starts npm without a shell, and stops the servers of the checks by their group of processes.
Node.js	22.18 or later, in version 22, 24, or 26 and later. Vitest does not support versions 23 and 25.
git	Any version, for `init --example`: it uses git to get the example app.

Make a new project

Terminal

npx @ingenioz-it/caits init my-app --example
cd my-app
npm run check

npx asks to install CAITS first: answer y.

The first line makes the project in the folder my-app:

It writes the files of the project (see What the command writes).
It writes package.json, with the scripts and the packages.
It installs the packages, with npm install.
It installs the browser of the end-to-end tests, with npx playwright install chromium.

npm can warn about install scripts and about vulnerabilities of the tools: the checks pass all the same.

npm run check makes sure that the installation is correct: it builds the app, checks the types, the lint and the architecture, and runs the tests: the unit tests with the coverage, the mutation tests and the end-to-end tests. Then npm run dev starts the app on http://localhost:3000.

--example writes a small app that shows each layer and each kind of test: the example app. Without --example, the project starts with one page, which shows "My app", and its end-to-end test.

Add CAITS to a project

CAITS fits a Marko app or a nearly empty folder. In a project with another structure, the architecture check fails until the code moves into contexts.

In the folder of the project:

Terminal, in the folder of the project

npx @ingenioz-it/caits init

The command writes only the files that the project does not have. It does not change the other files, except quality/caits/, which CAITS owns and writes again.
It adds to package.json only the values that it does not have: scripts, packages, type, imports, engines.
It adds to .gitignore the lines that it does not have.
It tells which files and which values of the project it kept. Compare them with those of node_modules/@ingenioz-it/caits/template/project/. There, the files .gitignore, .nvmrc and AGENTS.md have the names gitignore, nvmrc and AGENTS.

Without a folder name, the command works only in a folder that has a package.json: it keeps you from writing a project into the wrong folder by mistake. To use an empty folder, give its name, or . for the current folder.

What the command writes

The files of a new project

my-app/
├── package.json
├── tsconfig.json        extends quality/caits/tsconfig.json
├── .gitignore
├── .nvmrc
├── AGENTS.md            what an AI agent needs to know: the commands, where the code goes, the rules
├── quality/             the configuration of the tools: these files are yours
│   ├── architecture.mjs
│   ├── eslint.config.js
│   ├── playwright.config.ts
│   ├── stryker.config.mjs
│   ├── vite.config.ts
│   └── caits/           the defaults of CAITS: CAITS owns these files
├── src/
│   ├── backend/         the contexts of the backend, one folder for each context
│   ├── frontend/        the contexts of the frontend, one folder for each context
│   └── routes/_frontend/+page.marko   the first page
└── test/e2e/home.spec.ts              the first end-to-end test

With --example, src/ and test/e2e/ hold the example app instead.

Each file of quality/ imports the defaults of CAITS from quality/caits/, then changes them. Your file has the last word. To change a rule or a setting, see Change the rules and the tools.

Do not change the files of quality/caits/: npx caits update writes them again.

Update CAITS

First read what changed: the changelog gives each version, and what to do for a breaking change. Then install the last version of the package @ingenioz-it/caits:

Terminal, in the folder of the project

npm install --save-dev @ingenioz-it/caits@latest
npx caits update

npm install gets the new version of CAITS: its code and its commands.
npx caits update writes the defaults of the new version in quality/caits/. It does not change your files.
In a git repository, look at the changes with git diff quality/caits/. Then run npm run check.

If you forget step 2, the commands of CAITS (caits architecture, caits e2e…) show a warning: the version of quality/caits/ is not the version of CAITS.

npm update gets the fixes of the version that the project has (0.5.1 for 0.5.0), but not a new minor version (0.6.0), which can change how CAITS works. Run npx caits update after it too.

The versions of the tools

CAITS suggests a version for each tool: the version that CAITS uses itself. The project chooses.

init writes the suggested versions in package.json. After that, the versions are yours.
npx caits update tells which packages have a version that is not the one that CAITS suggests. It does not change them.

Options of `init`

Option	What it does
`--example`	Writes the example app in place of the first page, and adds the packages of the app (its fonts). git gets the app from the repository `IngeniozIT/caits-example`, at the tag of the version of CAITS.
`--no-install`	Writes the files, but installs nothing. Then run `npm install` and `npx playwright install chromium` yourself.
`--example-source <source>`	For the work on CAITS itself: writes the example of this source, a git repository with `#` and a tag or a branch, or a folder. `--example` is then not necessary.
`--caits <source>`	For the work on CAITS itself: npm gets CAITS from this source, for example a package that `npm pack` made: `file:/path/to/ingenioz-it-caits-0.5.1.tgz`. By default, the source is the version of the command on npm, or a later one with the same minor version (`^0.5.1`).

All the scripts and the commands of a project are in Commands.