typescript-backend-project-setup

What this skill does

# 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.conf