Skip to content
TSMC

Development

Requires Node.js ≥ 24 and pnpm.

Окно терминала
pnpm install
pnpm build   # build the web interface and the CLI (packages/cli/dist)
pnpm start   # http://127.0.0.1:3000, data in data/tsmc.db

Development: pnpm dev (API on :3000, the interface with hot reload on http://localhost:5173).

Checks:

Окно терминала
pnpm typecheck
pnpm test        # unit and API tests (vitest)
pnpm e2e         # builds the interface and runs browser tests (Playwright) on demo data

pnpm e2e needs a browser: pnpm --filter @tsmc/e2e exec playwright install chromium, or an installed Chrome/Edge via PW_CHANNEL=chrome / PW_CHANNEL=msedge.

CI (GitHub Actions, .github/workflows/ci.yml) runs type checks, tests and browser tests on every push and PR, and builds the Docker image and checks that it starts. From main the image is published as ghcr.io/<owner>/tsmc:latest, from v* tags with the version number. The report of failed browser tests is kept as the playwright-report artifact.

On first start the interface offers to create an administrator.

Branch workflow

Section titled “Branch workflow”

Each stage is developed in its own branch stage-N-<name>, created from the current main. When a stage is done, the branch is merged into main with --no-ff, so the boundary of every stage is visible in the history. Stage branches are not deleted.

Documentation

Section titled “Documentation”

This site is the packages/site package (Astro Starlight): the Russian pages are in src/content/docs, the English ones in src/content/docs/en. A documentation change goes into the same pull request as the code change.

Окно терминала
pnpm --filter @tsmc/site dev     # http://localhost:4321, reloads on edits
pnpm --filter @tsmc/site build   # builds into packages/site/dist

The reference pages are built from the code by scripts/generate.ts before every build: the API routes with their roles and request fields, the CLI help and the list of changes from merged pull requests. The build fails when:

  • an API route has no description in src/api-docs.ts (or a described route is gone);
  • a TSMC_* variable the server or the CLI reads is missing from Environment variables;
  • a link between pages leads nowhere.

The .github/workflows/docs.yml workflow builds the site on every pull request and publishes it to Cloudflare Pages: main as the site itself, a pull request as a preview of its branch (needs the CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID secrets).

Publishing to Cloudflare Pages

Section titled “Publishing to Cloudflare Pages”
  1. Sign in at dash.cloudflare.com (the free plan is enough).
  2. Account ID: on the dashboard home page, “Copy account ID” in the account menu, or in the address dash.cloudflare.com/<account ID>/… — a 32-character string.
  3. API token: the profile icon → My Profile → API Tokens → Create Token → Create Custom Token. A name such as tsmc docs from GitHub; Permissions: Account · Cloudflare Pages · Edit; Account Resources: Include · your account. Continue to summary → Create Token, and copy the token — it is shown once.
  4. Repository secrets: GitHub → Settings → Secrets and variables → Actions → New repository secret: CLOUDFLARE_API_TOKEN (the token) and CLOUDFLARE_ACCOUNT_ID (the account ID).
  5. First publish: Actions → Docs → Run workflow on main (or the next merge to main). The tsmc-docs project is created by itself; the site address is in the output of the “Publish to Cloudflare Pages” step, usually https://tsmc-docs.pages.dev (Cloudflare adds a suffix when the name is taken).
  6. Site address: Settings → Secrets and variables → Actions → Variables → New repository variable DOCS_URL with that address — canonical links and the sitemap are built from it.

A pull request’s preview is at https://<branch>.tsmc-docs.pages.dev. To keep the site to your own people, put it behind a Cloudflare Access sign-in (Zero Trust → Access → Applications), free for small teams.

The home page of the site is the product page (src/landing, the texts in both languages in content.ts). Its screenshots are the real interface on demo data; after visible changes of the interface, take them again:

Окно терминала
pnpm build && pnpm --filter @tsmc/e2e screens   # PW_CHANNEL=msedge|chrome for an installed browser

The script starts its own demo server and puts the shots into packages/site/public/screens/{ru,en}.

Astro loads native modules (the compiler, the Markdown parser). On Windows an application control policy (Smart App Control) may block them, or the Microsoft Visual C++ Redistributable (x64) may be missing — then the site does not build locally. CI always builds it: the built site can be downloaded from the workflow run (the docs-site artifact).