Skip to content

QUICKSTART.md

Latest commit

 

History

History
179 lines (136 loc) · 6.57 KB

QUICKSTART.md

File metadata and controls

179 lines (136 loc) · 6.57 KB
Raw

Quickstart

Get a spec-compliant project running, develop against it, and keep it in sync as the spec evolves.

Prerequisites

  • Node.js ≥ 22
  • npm, pnpm, or yarn

1. Install Clearstack

Clearstack is a dev dependency — it lives in your project and manages spec docs, configs, and compliance checks.

npm install --save-dev @techninja/clearstack
# or
pnpm add -D @techninja/clearstack

2. Scaffold Your Project

From your project root:

npx clearstack init            # interactive
npx clearstack init -y         # non-interactive (fullstack defaults)
npx clearstack init --static   # non-interactive, static mode
npx clearstack init -y --static # same as above

The interactive prompt asks for:

Prompt Default Notes
Project name current directory name Used in package.json and templates
Description A Clearstack project Goes into package.json
Mode — Fullstack: Express + WebSocket + JSON DB + SSE. Static: localStorage only
Port 3000 Fullstack only. Set in .env

If a package.json already exists, Clearstack merges into it — your existing fields (author, license, engines, keywords, etc.) are preserved.

3. What Gets Created

your-project/
├── .configs/              # ✏️ Scaffolded once — yours to customize
├── .github/               # CI workflow, PR + issue templates
├── docs/
│   ├── clearstack/        # ⟳ Managed — spec docs, synced on update
│   └── app-spec/          # ✏️ Yours — project-specific specs
├── scripts/               # ✏️ Yours — setup, test, vendor-deps, build-icons
├── src/                   # ✏️ Yours — the app, served directly
│   ├── index.html         # App shell with import map
│   ├── vendor/            # Vendored ES modules (generated, gitignored)
│   ├── icons.json         # Icon sprite (generated, gitignored)
│   ├── components/        # atoms/, molecules/, organisms/
│   ├── pages/             # Route-level views
│   ├── store/             # Hybrids store models
│   ├── styles/            # Global CSS
│   ├── router/            # Client-side routing
│   ├── utils/             # Shared helpers
│   ├── api/               # Server routes (fullstack only)
│   └── server.js          # Express entry point
├── data/                  # JSON DB seed (fullstack only)
├── .env                   # Defaults (committed)
├── .env.local             # Overrides (gitignored)
└── package.json

src/ is the entire app. node src/server.js serves it. For static deploy, point your CDN at src/. No build step.

4. Install and Run

npm install

postinstall runs vendor-deps.js (copies hybrids to src/vendor/) and build-icons.js (extracts Lucide SVGs to src/icons.json).

Fullstack

npm run dev

5. Development Rules

  • ≤150 lines per .js / .css file. Add // SPLIT CANDIDATE: at ~120 lines.
  • Light DOM by default. No shadowRoot. Shared styles in src/styles/ apply everywhere.
  • JSDoc for types. @typedef, @param, @returns — validated by tsc --checkJs.
  • No build step. Every file runs as-is in the browser via ES modules and import maps.

6. Project-Specific Specs

docs/app-spec/ is yours. Upstream updates never touch it. Use it for:

  • Entity schemas and relationships
  • Project-specific component patterns
  • API documentation beyond the base spec
  • Architecture decisions (ADRs)
  • Deviations from the base spec (with rationale)

See docs/app-spec/README.md for examples.

7. Updating

When Clearstack releases a new version:

npm update @techninja/clearstack    # bump the package
npm run spec update                 # sync docs, skip existing configs
npm run spec update --force         # sync docs + overwrite configs
git diff docs/ .configs/            # review what changed

This updates:

  • docs/clearstack/*.md — spec documentation (always overwritten)
  • .configs/* — skipped if already exists (your customizations are safe)
  • .configs/* with --force — overwritten with latest defaults

This never touches:

  • docs/app-spec/ — your project specs
  • src/ — your code
  • scripts/ — your build scripts
  • .env — your thresholds and settings

8. Spec Compliance

npm run spec           # interactive menu
npm run spec all       # full check
npm run spec code      # code files ≤150 lines
npm run spec docs      # doc files ≤500 lines
npm run spec lint      # ESLint + Stylelint + Markdown
npm run spec lint es   # ESLint only
npm run spec format    # Prettier
npm run spec imports   # import map aliases
npm run spec types     # JSDoc types (all jsconfigs)
npm run spec audit     # security audit
npm test               # Node + browser tests

Configuring thresholds

Override defaults in .env:

SPEC_CODE_MAX_LINES=150
SPEC_DOCS_MAX_LINES=500
SPEC_CODE_EXTENSIONS=.js,.css
SPEC_DOCS_EXTENSIONS=.md
SPEC_IGNORE_DIRS=node_modules,src/vendor,.git,.configs

9. CI Pipeline

The scaffolded .github/workflows/spec.yml runs all checks on every PR:

spec all → lint + format + code + docs + imports + types + audit

Summary

Task Command
Install Clearstack npm install -D @techninja/clearstack
Scaffold (fullstack) npx clearstack init
Scaffold (static) npx clearstack init --static
Install dependencies npm install
Start dev server npm run dev
Lint + format npm run spec lint && npm run spec format
Type check npm run spec types
Run tests npm test
Full spec check npm run spec
Update spec + configs npm run spec update
Review spec changes git diff docs/ .configs/