weseek__growi/.claude/skills/tech-stack/SKILL.md

---

name: tech-stack description: GROWI technology stack, build tools, and global commands. Auto-invoked for all GROWI development work.

user-invocable: false

GROWI Tech Stack

Core Technologies

• TypeScript ~5.0.0
• Node.js ^18 || ^20
• MongoDB with Mongoose ^6.13.6 (apps/app)
• MySQL with TypeORM 0.2.x (apps/slackbot-proxy)

Frontend Framework

• React 18.x
• Next.js (Pages Router) - Full-stack framework for apps/app

State Management & Data Fetching (Global Standard)

• Jotai - Atomic state management (recommended for all packages with UI state)

  • Use for UI state, form state, modal state, etc.
  • Lightweight, TypeScript-first, minimal boilerplate

• SWR ^2.3.2 - Data fetching with caching

  • Use for API data fetching with automatic revalidation
  • Works seamlessly with RESTful APIs

Why Jotai + SWR?

• Separation of concerns: Jotai for UI state, SWR for server state
• Performance: Fine-grained reactivity (Jotai) + intelligent caching (SWR)
• Type safety: Both libraries have excellent TypeScript support
• Simplicity: Minimal API surface, easy to learn

Build & Development Tools

Package Management

• pnpm Package manager (faster, more efficient than npm/yarn)

Monorepo Orchestration

• Turborepo ^2.1.3 - Build system with caching and parallelization

Linter & Formatter

• Biome ^2.2.6 - Unified linter and formatter (recommended)

  • Replaces ESLint + Prettier
  • Significantly faster (10-100x)

  • Configuration: biome.json

    # Lint and format check
    biome check <files>
    
    # Auto-fix issues
    biome check --write <files>
    

• Stylelint ^16.5.0 - SCSS/CSS linter

  • Configuration: .stylelintrc.js

    # Lint styles
    stylelint "src/**/*.scss"
    

Testing

• Vitest ^2.1.1 - Unit and integration testing (recommended)

  • Fast, Vite-powered
  • Jest-compatible API
  • Configuration: vitest.workspace.mts

• React Testing Library ^16.0.1 - Component testing

  • User-centric testing approach

• vitest-mock-extended ^2.0.2 - Type-safe mocking

  • TypeScript autocomplete for mocks

• Playwright ^1.49.1 - E2E testing

  • Cross-browser testing

Essential Commands (Global)

Development

# Start all dev servers (apps/app + dependencies)
turbo run dev

# Start dev server for specific package
turbo run dev --filter @growi/app

# Install dependencies for all packages
pnpm install

# Bootstrap (install + build dependencies)
turbo run bootstrap

Testing & Quality

# Run a specific test file (from package directory, e.g. apps/app)
pnpm vitest run yjs.integ          # Partial file name match
pnpm vitest run helper.spec        # Works for any test file
pnpm vitest run yjs.integ --repeat=10  # Repeat for flaky test detection

# Run ALL tests for a package (uses Turborepo caching)
turbo run test --filter @growi/app

# Run linters for specific package
turbo run lint --filter @growi/app

Building

# Build all packages
turbo run build

# Build specific package
turbo run build --filter @growi/core

Turborepo Task Filtering

Turborepo uses --filter to target specific packages:

# Run task for single package
turbo run test --filter @growi/app

# Run task for multiple packages
turbo run build --filter @growi/core --filter @growi/ui

# Run task for package and its dependencies
turbo run build --filter @growi/app...

Important Configuration Files

Workspace Configuration

• pnpm-workspace.yaml - Defines workspace packages

  packages:
  - 'apps/*'
  - 'packages/*'
  

Build Configuration

• turbo.json - Turborepo pipeline configuration
  • Defines task dependencies, caching, and outputs

TypeScript Configuration

• tsconfig.base.json - Base TypeScript config extended by all packages
  • Target: ESNext
  • Module: ESNext
  • Strict Mode: Enabled (strict: true)
  • Module Resolution: Bundler
  • Allow JS: true (for gradual migration)
  • Isolated Modules: true (required for Vite, SWC)

Package-specific tsconfig.json example:

{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "**/*.spec.ts"]
}

Testing Configuration

• vitest.workspace.mts - Vitest workspace config
  • Defines test environments (Node.js, happy-dom)
  • Configures coverage

Linter Configuration

• biome.json - Biome linter/formatter config
  • Rules, ignore patterns, formatting options

Development Best Practices

Command Usage

1. Use Turborepo for full-package tasks (all tests, lint, build):
   • ✅ turbo run test --filter @growi/app
   • ❌ cd apps/app && pnpm test (bypasses Turborepo caching)

2. Use vitest directly for individual test files (from package directory):

   • ✅ pnpm vitest run yjs.integ (simple, fast)
   • ❌ turbo run test --filter @growi/app -- yjs.integ (unnecessary overhead)

3. Use pnpm for package management:

   • ✅ pnpm install
   • ❌ npm install or yarn install

4. Run tasks from workspace root:

   • Turborepo handles cross-package dependencies
   • Caching works best from root

State Management Guidelines

1. Use Jotai for UI state:

   // Example: Modal state
   import { atom } from 'jotai';
   
   export const isModalOpenAtom = atom(false);
   

2. Use SWR for server state:

   // Example: Fetching pages
   import useSWR from 'swr';
   
   const { data, error, isLoading } = useSWR('/api/pages', fetcher);
   

3. Avoid mixing concerns:

   • Don't store server data in Jotai atoms
   • Don't manage UI state with SWR

Migration Notes

• New packages: Use Biome + Vitest from the start
• Legacy packages: Can continue using existing tools during migration
• Gradual migration: Prefer updating to Biome + Vitest when modifying existing files

Technology Decisions

Why Next.js Pages Router (not App Router)?

• GROWI started before App Router was stable
• Pages Router is well-established and stable
• Migration to App Router is being considered for future versions

Why Jotai (not Redux/Zustand)?

• Atomic approach: More flexible than Redux, simpler than Recoil
• TypeScript-first: Excellent type inference
• Performance: Fine-grained reactivity, no unnecessary re-renders
• Minimal boilerplate: Less code than Redux

Why SWR (not React Query)?

• Simplicity: Smaller API surface
• Vercel integration: Built by Vercel (same as Next.js)
• Performance: Optimized for Next.js SSR/SSG

Why Biome (not ESLint + Prettier)?

• Speed: 10-100x faster than ESLint
• Single tool: Replaces both ESLint and Prettier
• Consistency: No conflicts between linter and formatter
• Growing ecosystem: Active development, Rust-based

Package-Specific Tech Stacks

Different apps in the monorepo may use different tech stacks:

• apps/app: Next.js + Express + MongoDB + Jotai + SWR
• apps/pdf-converter: Ts.ED + Puppeteer
• apps/slackbot-proxy: Ts.ED + TypeORM + MySQL

See package-specific CLAUDE.md or skills for details.