typescript-backend-project-setup

# NX Monorepo TypeScript Backend Project Setup > 🚨 **DO NOT USE PLAN MODE.** This skill IS the plan. Follow the steps exactly as written. > ⚠️ **Check NX docs for latest conventions:** https://nx.dev/docs/getting-started/start-new-project > NX evolves quickly. Verify these instructions against current NX best practices before use. Set up NX monorepo for TypeScript backend projects with maximum type safety, strict linting, 100% test coverage, and AI-optimized project structure. ## Contents 1. [Phase 1: Define Project Context](#phase-1-define-project-context) - Gather requirements 2. [Phase 2: Create NX Workspace](#phase-2-create-nx-workspace) - Run NX generator 3. [Phase 3: Install Dependencies](#phase-3-install-dependencies) - Add plugins and tools 4. [Phase 4: Create Initial Projects](#phase-4-create-initial-projects) - Generate packages and apps 5. [Phase 5: Add Claude Code Integration](#phase-5-add-claude-code-integration) - Copy AI guardrails and docs 6. [Phase 6: Enforce Strict Standards](#phase-6-enforce-strict-standards) - Patch configs 7. [Phase 7: Establish Coding Conventions](#phase-7-establish-coding-conventions) - Add skill content 8. [Phase 8: Activate Git Hooks](#phase-8-activate-git-hooks) - Enable pre-commit checks 9. [Phase 9: Verify Setup](#phase-9-verify-setup) - Confirm everything works 10. [Phase 10: Document Architecture](#phase-10-document-architecture-optional) - Optional interview ## When This Activates - User requests: "set up typescript backend project", "create backend project", "initialize typescript backend", "create monorepo" - Working in an empty or near-empty project folder - User asks for backend project scaffolding or boilerplate ## Template Location This skill uses a template located at: `typescript-backend-project-setup/template/` The template contains only files NX cannot create: Claude Code integration, documentation structure, and git hooks. Before starting, ask the user for the full path to the claude-skillz repository so you can locate the template. ## Setup Procedure ### Phase 1: Define Project Context Ask the user: 1. **Workspace name** - What should this monorepo be called? (lowercase, hyphens ok) 2. **Domain description** - Brief description of what this project does 3. **Claude-skillz path** - What is the full path to the claude-skillz repository on your system? 4. **Target directory** - Where should the project be created? (defaults to current directory) 5. **Initial packages** - List any publishable packages to create (e.g., "query, builder, cli") 6. **Initial apps** - List any applications to create (e.g., "api, docs") ### Phase 2: Create NX Workspace **Priority: Commands > Installs > Patch files (last resort)** Run the NX workspace generator: ```bash npx create-nx-workspace@latest [workspace-name] --preset=ts --pm=pnpm --nxCloud=skip --interactive=false ``` This creates: - `nx.json` - NX configuration - `tsconfig.base.json` - Base TypeScript config - `package.json` - Root package with NX scripts - `pnpm-workspace.yaml` - Workspace definition - `.gitignore` - Standard ignores **Patch .gitignore - Add test-output:** Add `test-output` to `.gitignore` (vitest coverage output): ``` test-output ``` **Checkpoint:** Verify `nx report` shows NX version. ### Phase 3: Install Dependencies Add testing and code quality tools: ```bash # Add NX plugins nx add @nx/vitest nx add @nx/eslint nx add @nx/node # Required for creating applications # Install testing dependencies pnpm add -D vitest @vitest/coverage-v8 # Install ESLint dependencies (required for strict config) pnpm add -D typescript-eslint @nx/eslint-plugin eslint-plugin-functional # Install git hooks pnpm add -D husky lint-staged ``` Adding `@nx/vitest`. Provides integrated test runner with coverage reporting. Adding `@nx/eslint`. Provides consistent linting across all projects. Adding `@nx/node`. Required for creating Node.js applications. Adding `husky` and `lint-staged`. Provides pre-commit verification gate. ### Phase 4: Create Initial Projects **If user specified packages in Phase 1, create them:** ```bash # For each package (publishable library with vitest) nx g @nx/js:library packages/[pkg-name] --publishable --importPath=@[workspace-name]/[pkg-name] --bundler=tsc --unitTestRunner=vitest ``` **If user specified apps in Phase 1, create them:** ```bash # For each app (node application - vitest NOT supported, use none) nx g @nx/node:application apps/[app-name] --unitTestRunner=none ``` 🚨 **IMPORTANT:** - `@nx/js:library` supports `--unitTestRunner=vitest` - `@nx/node:application` only supports `--unitTestRunner=jest|none` (NOT vitest) After creating projects, run `nx sync` to update TypeScript project references. ### Phase 5: Add Claude Code Integration Copy template files (only what NX can't create): **Claude Code Integration:** ```bash cp -r [claude-skillz-path]/typescript-backend-project-setup/template/CLAUDE.md [target-directory]/ cp -r [claude-skillz-path]/typescript-backend-project-setup/template/AGENTS.md [target-directory]/ cp -r [claude-skillz-path]/typescript-backend-project-setup/template/.claude [target-directory]/ ``` Adding `CLAUDE.md`. Provides AI context, commands, and project conventions. Adding `.claude/settings.json`. Provides permission guardrails and hook configuration. Adding `.claude/hooks/block-dangerous-commands.sh`. Prevents destructive git operations (--force, --hard, --no-verify). **Documentation Structure:** ```bash cp -r [claude-skillz-path]/typescript-backend-project-setup/template/docs [target-directory]/ cp [claude-skillz-path]/typescript-backend-project-setup/template/repository-setup-checklist.md [target-directory]/ ``` Adding `docs/conventions/`. Provides coding standards and workflow documentation. Adding `docs/architecture/`. Provides system design and domain terminology templates. Adding `docs/project/`. Provides project vision and planning templates. **Git Hooks:** ```bash cp -r [claude-skillz-path]/typescript-backend-project-setup/template/.husky [target-directory]/ ``` Adding `.husky/pre-commit`. Provides pre-commit verification (lint, typecheck, test). **Custom ESLint Rules:** ```bash cp -r [claude-skillz-path]/typescript-backend-project-setup/template/.eslint-rules [target-directory]/ ``` Adding `.eslint-rules/no-generic-names.js`. Custom rule that bans generic names (utils, helpers, service, manager) in filenames and class names. **Make scripts executable:** ```bash chmod +x [target-directory]/.claude/hooks/block-dangerous-commands.sh ``` **Replace placeholders in copied files:** | Placeholder | Replace With | |-------------|--------------| | `{{WORKSPACE_NAME}}` | User's workspace name | | `{{WORKSPACE_DESCRIPTION}}` | User's domain description | | `{{DOMAIN_NAME}}` | User's workspace name (used as context name in glossary) | | `{{DOMAIN_DESCRIPTION}}` | User's domain description | Files with placeholders: - `CLAUDE.md` - `docs/conventions/codebase-structure.md` - `docs/architecture/domain-terminology/contextive/definitions.glossary.yml` - `docs/project/project-overview.md` ### Phase 6: Enforce Strict Standards These patches add our strict standards to NX-generated configs. **Patch nx.json - Add lint dependency to build/test:** Add to `targetDefaults.build.dependsOn`: ```json "dependsOn": ["lint", "^build"] ``` Add to `targetDefaults.test`: ```json "dependsOn": ["lint"] ``` This ensures AI gets immediate lint feedback on any change. **Patch tsconfig.base.json - Add strict TypeScript flags:** Add these to `compilerOptions`: ```json { "noUncheckedIndexedAccess": true, "noImplicitOverride": true, "noFallthroughCasesInSwitch": true, "noPropertyAccessFromIndexSignature": true, "noUnusedLocals": true, "noUnusedParameters": true, "noImplicitReturns": true, "exactOptionalPropertyTypes": true, "verbatimModuleSyntax": true } ``` **Patch eslint.config.mjs - Add strict rules:** **IMPORTANT:** Completely overwrite `eslint.config.mjs` with this exact content (do not merge, do not patch - replace the entire file): ```javascript import nx from '@nx/eslint-plugin'; import tseslint from 'typescript-eslint'; import noGenericNames from './.eslint-rules/no-generic-names.js'; const customRules = { plugins: { custom: { rules: { 'no-generic-names': noGenericNames, }, }, }, }; export default tseslint.config( ...nx.configs['flat/base'], ...nx.configs['flat/typescript'], ...nx.configs['flat/javascript'], { ignores: ['**/dist', '**/out-tsc', '**/node_modules', '**/.nx', '*.config.ts', '*.config.mjs', '*.config.js', 'vitest.workspace.ts'], }, customRules, { files: ['**/*.ts', '**/*.tsx'], rules: { // Custom rule: no generic names 'custom/no-generic-names': 'error', // No comments - forces self-documenting code 'no-warning-comments': 'off', 'multiline-comment-style': 'off', 'capitalized-comments': 'off', 'no-inline-comments': 'error', 'spaced-comment': 'off', // Ban let - use const only 'no-restricted-syntax': [ 'error', { selector: 'VariableDeclaration[kind="let"]', message: 'Use const. Avoid mutation.', }, ], 'prefer-const': 'error', 'no-var': 'error', // No any types '@typescript-eslint/no-explicit-any': 'error', '@typescript-eslint/no-unsafe-assignment': 'error', '@typescript-eslint/no-unsafe-member-access': 'error', '@typescript-eslint/no-unsafe-call': 'error', '@typescript-eslint/no-unsafe-return': 'error', // No type assertions - fix the types instead '@typescript-eslint/consistent-type-assertions': ['error', { assertionStyle: 'never' }], // Ban generic folder imports (not lib - that's NX convention) 'no-restricted-imports': [ 'error', { patterns: [ { group: ['*/utils/*', '*/utils'], message: 'No utils folders. Use domain-specific names.' }, { group: ['*/helpers/*', '*/helpers'], message: 'No helpers folders. Use domain-specific names.' }, { group: ['*/common/*', '*/common'], message: 'No common folders. Use domain-specific names.' }, { group: ['*/shared/*', '*/shared'], message: 'No shared folders. Use domain-specific names.' }, { group: ['*/core/*', '*/core'], message: 'No core folders. Use domain-specific names.' }, ], }, ], // Complexity limits 'max-lines': ['error', { max: 400, skipBlankLines: true, skipComments: true }], 'max-depth': ['error', 3], 'complexity': ['error', 12], // Naming conventions '@typescript-eslint/naming-convention': [ 'error', { selector: 'variable', format: ['camelCase'], }, { selector: 'variable', modifiers: ['const'], format: ['camelCase', 'UPPER_CASE'], }, { selector: 'function', format: ['camelCase'], }, { selector: 'parameter', format: ['camelCase'], leadingUnderscore: 'allow', }, { selector: 'typeLike', format: ['PascalCase'], }, { selector: 'enumMember', format: ['PascalCase'], },