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 - Gather requirements
2. Phase 2: Create NX Workspace - Run NX generator
3. Phase 3: Install Dependencies - Add plugins and tools
4. Phase 4: Create Initial Projects - Generate packages and apps
5. Phase 5: Add Claude Code Integration - Copy AI guardrails and docs
6. Phase 6: Enforce Strict Standards - Patch configs
7. Phase 7: Establish Coding Conventions - Add skill content
8. Phase 8: Activate Git Hooks - Enable pre-commit checks
9. Phase 9: Verify Setup - Confirm everything works
10. Phase 10: Document Architecture - 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:

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

.gitignore

test-output

Checkpoint: Verify

nx report

Phase 3: Install Dependencies

Add testing and code quality tools:

# 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

Adding

@nx/eslint

Adding

@nx/node

Adding

husky

lint-staged

Phase 4: Create Initial Projects

If user specified packages in Phase 1, create them:

# 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:

# 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

Phase 5: Add Claude Code Integration

Copy template files (only what NX can't create):

Claude Code Integration:

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

Adding

.claude/settings.json

Adding

.claude/hooks/block-dangerous-commands.sh

Documentation Structure:

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/

Adding

docs/architecture/

Adding

docs/project/

Git Hooks:

cp -r [claude-skillz-path]/typescript-backend-project-setup/template/.husky [target-directory]/

Adding

.husky/pre-commit

Custom ESLint Rules:

cp -r [claude-skillz-path]/typescript-backend-project-setup/template/.eslint-rules [target-directory]/

Adding

.eslint-rules/no-generic-names.js

Make scripts executable:

chmod +x [target-directory]/.claude/hooks/block-dangerous-commands.sh

Replace placeholders in copied files:

{{WORKSPACE_NAME}}

{{WORKSPACE_DESCRIPTION}}

{{DOMAIN_NAME}}

{{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

"dependsOn": ["lint", "^build"]

Add to

targetDefaults.test

"dependsOn": ["lint"]

This ensures AI gets immediate lint feedback on any change.

Patch tsconfig.base.json - Add strict TypeScript flags:

Add these to

compilerOptions

{
  "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

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'],
        },
        {
          selector: 'objectLiteralProperty',
          format: null,
        },
      ],
    },
  },
  {
    files: ['**/*.ts', '**/*.tsx'],
    languageOptions: {
      parserOptions: {
        projectService: true,
        tsconfigRootDir: import.meta.dirname,
      },
    },
  }
);

This enforces:

• No generic names - Custom rule bans utils, helpers, service, manager, etc. in filenames and class names
• No

  let

  - Only

  const

  allowed via no-restricted-syntax
• No type assertions - Fix the types, don't cast
• No generic folders - Bans imports from utils/, helpers/, common/, shared/, core/
• Complexity limits - Max 400 lines, max depth 3, cyclomatic complexity 12
• No inline comments - Forces self-documenting code
• No

  any

  types - Anywhere
• Naming conventions - camelCase for variables/functions, PascalCase for types

Patch package.json - Add scripts and lint-staged:

Add these to the root package.json:

{
  "scripts": {
    "build": "nx run-many -t build",
    "test": "nx run-many -t test",
    "lint": "nx run-many -t lint",
    "typecheck": "nx run-many -t typecheck",
    "verify": "nx run-many -t lint,typecheck && nx run-many -t test --coverage",
    "prepare": "husky"
  },
  "lint-staged": {
    "*.ts": ["eslint --fix"]
  }
}

Patch vitest.config.mts files - Add 100% coverage thresholds:

For EACH project created in Phase 4 that has a

vitest.config.mts

coverage: {
  reportsDirectory: './test-output/vitest/coverage',
  provider: 'v8' as const,
  thresholds: {
    lines: 100,
    statements: 100,
    functions: 100,
    branches: 100,
  },
},

This enforces 100% test coverage - tests will FAIL if coverage drops below 100%.

Phase 7: Establish Coding Conventions

Copy content from claude-skillz skills to the docs:

Testing conventions:

• Read:

  [claude-skillz-path]/writing-tests/SKILL.md

• Write to:

  docs/conventions/testing.md

Adding

docs/conventions/testing.md

Software design conventions:

• Read:

  [claude-skillz-path]/software-design-principles/SKILL.md

• Write to:

  docs/conventions/software-design.md

Adding

docs/conventions/software-design.md

Phase 8: Activate Git Hooks

Initialize husky, then overwrite the default pre-commit with our version:

cd [target-directory]
npx husky init
# husky init creates a default pre-commit - overwrite it with ours:
cp [claude-skillz-path]/typescript-backend-project-setup/template/.husky/pre-commit .husky/pre-commit

Phase 9: Verify Setup

# Check NX is working
nx report

# View empty workspace
nx graph

Review the

repository-setup-checklist.md

Checkpoint: All verification commands pass. Ready for first commit.

Phase 10: Document Architecture (Optional)

Offer to interview the user to fill in placeholder content:

Architecture Overview (

docs/architecture/overview.md

• "What systems does this interact with?"
• "Who are the primary users?"
• "What are the main technical components?"

Domain Terminology (

docs/architecture/domain-terminology/contextive/definitions.glossary.yml

• "What are the key terms in this domain?"
• "How would you define [term] to a new team member?"

Project Overview (

docs/project/project-overview.md

• "What problem are you solving?"
• "Who are the users and what do they need?"
• "What are your non-negotiable principles?"
• "What are the project phases?"

Summary

This skill creates an NX monorepo using a command-first approach:

1. create-nx-workspace

   for foundation

2. nx add

   for plugins

3. pnpm add

   for dependencies
4. Copy template files (only what NX can't create)
5. Patch configs (last resort)
6. Verify setup

The result provides:

• Maximum type safety - strict tsconfig, TypeScript project references
• Strict linting - no comments, naming conventions, no mutation
• 100% test coverage - with sensible excludes
• NX orchestration - caching, affected commands, dependency graph
• AI guardrails - protected configs, blocked dangerous commands
• Scalable structure - apps and packages pattern with workspace:* dependencies

For adding projects after setup, see

docs/conventions/codebase-structure.md

Verification Mode

Trigger: "verify typescript setup", "check project setup", "audit monorepo config"

Use this to verify an existing repo has all required configurations.

Step 1: Discover all projects

find . -name "package.json" -not -path "*/node_modules/*" -not -path "*/.nx/*"

Step 2: ESLint Config Verification

Read

eslint.config.mjs

• Import of

  .eslint-rules/no-generic-names.js

• Rule

  custom/no-generic-names: 'error'

• Rule

  no-restricted-syntax

  with

  VariableDeclaration[kind="let"]

  selector
• Rule

  @typescript-eslint/consistent-type-assertions

  with

  assertionStyle: 'never'

• Rule

  no-restricted-imports

  with patterns for utils, helpers, common, shared, core
• Rules

  max-lines: 400

  ,

  max-depth: 3

  ,

  complexity: 12

If any missing: List what's missing and offer to fix.

Step 3: Vitest Config Verification

For EACH project discovered in Step 1:

1. Check if

   vitest.config.mts

   exists in that project directory
2. If exists, read it and verify

   coverage.thresholds

   contains:

   • lines: 100

   • statements: 100

   • functions: 100

   • branches: 100

If any project missing thresholds: List which projects are non-compliant and offer to fix.

Step 4: Git Hooks Verification

• .husky/pre-commit

  contains

  lint-staged

  and

  verify

• package.json

  has

  lint-staged

  config

Step 5: Gitignore Verification

• .gitignore

  contains

  test-output

  on its own line

Step 6: Report

Output a summary:

✓ ESLint: All rules configured
✗ Vitest: 2/6 projects missing coverage thresholds
  - apps/eclair
  - apps/docs
✓ Git Hooks: Configured
✓ Gitignore: test-output ignored

If failures: Offer to fix all issues automatically.