|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +This is `@lenne.tech/nuxt-base`, a Nuxt module that provides GraphQL integration and code generation capabilities for Nuxt applications. The module focuses on GraphQL codegen, easy GraphQL syntax, and authentication helpers. |
| 8 | + |
| 9 | +## Development Commands |
| 10 | + |
| 11 | +### Core Development |
| 12 | +- `npm run dev:prepare` - Generate type stubs and prepare the development environment |
| 13 | +- `npm run dev` - Start development server with playground app on port 3001 |
| 14 | +- `npm run dev:generate-types` - Start dev server with type generation enabled (GENERATE_TYPES=1) |
| 15 | +- `npm run dev:build` - Build the playground application |
| 16 | + |
| 17 | +### Building and Testing |
| 18 | +- `npm run build` - Build the module using nuxt-module-build |
| 19 | +- `npm run test` - Run tests with Vitest |
| 20 | +- `npm run test:watch` - Run tests in watch mode |
| 21 | + |
| 22 | +### Code Quality |
| 23 | +- `npm run lint` - Run ESLint on TypeScript, JavaScript, and Vue files |
| 24 | +- `npm run lint:fix` - Run ESLint with auto-fix |
| 25 | + |
| 26 | +### Release Management |
| 27 | +- `npm run release` - Create a new release with standard-version and push to main |
| 28 | +- `npm run release:minor` - Create a minor release |
| 29 | +- `npm run release:major` - Create a major release |
| 30 | + |
| 31 | +### Utilities |
| 32 | +- `npm run reinit` - Complete reinstall (removes lock files, node_modules, clears cache) |
| 33 | + |
| 34 | +## Architecture Overview |
| 35 | + |
| 36 | +### Module Structure |
| 37 | +- **`src/module.ts`** - Main Nuxt module definition with configuration options and setup logic |
| 38 | +- **`src/generate.ts`** - GraphQL type generation and composable creation logic |
| 39 | +- **`src/runtime/`** - Runtime code that gets bundled with the module |
| 40 | + |
| 41 | +### Runtime Architecture |
| 42 | +The runtime is organized into several key directories: |
| 43 | + |
| 44 | +- **`classes/`** - Core classes including GraphQL type helpers and standard utilities |
| 45 | +- **`composables/`** - Vue composables for GraphQL operations (query, mutation, subscription) and auth |
| 46 | +- **`enums/`** - GraphQL-related enums and request types |
| 47 | +- **`interfaces/`** - TypeScript interfaces for GraphQL operations and configuration |
| 48 | +- **`plugins/`** - Nuxt plugins for cookies, GraphQL meta, WebSocket, and auth |
| 49 | +- **`states/`** - Pinia/state management for authentication |
| 50 | + |
| 51 | +### Key Features |
| 52 | +1. **GraphQL Code Generation** - Automatically generates TypeScript types and composables from GraphQL schema |
| 53 | +2. **Authentication System** - Built-in auth state management with JWT token handling |
| 54 | +3. **WebSocket Support** - Real-time GraphQL subscriptions via WebSocket |
| 55 | +4. **Type Safety** - Full TypeScript support with generated types |
| 56 | + |
| 57 | +### Configuration |
| 58 | +Module configuration happens in `nuxt.config.ts` under the `nuxtBase` key: |
| 59 | +```typescript |
| 60 | +nuxtBase: { |
| 61 | + generateTypes: boolean, // Enable/disable type generation |
| 62 | + gqlHost: string, // GraphQL endpoint URL |
| 63 | + host: string, // Base host URL |
| 64 | + schema: string, // Path to GraphQL schema file |
| 65 | + storagePrefix: string, // Local storage prefix for auth tokens |
| 66 | + disableGraphql: boolean, // Completely disable GraphQL features |
| 67 | + registerAuthPlugins: boolean, // Enable auth plugins |
| 68 | + registerCookiePlugin: boolean, // Enable cookie plugin |
| 69 | + autoImport: boolean // Enable auto-import of generated composables |
| 70 | +} |
| 71 | +``` |
| 72 | + |
| 73 | +### Playground Application |
| 74 | +The `playground/nuxt-app/` directory contains a complete Nuxt application for testing the module: |
| 75 | +- Uses the module in development mode |
| 76 | +- Includes a GraphQL server in `playground/server/` |
| 77 | +- Demonstrates auth flows, GraphQL operations, and real-time features |
| 78 | + |
| 79 | +### Type Generation Process |
| 80 | +When `generateTypes: true` or `GENERATE_TYPES=1`: |
| 81 | +1. Module loads GraphQL schema from file or introspects remote endpoint |
| 82 | +2. Generates TypeScript types in `src/base/default.ts` |
| 83 | +3. Creates typed composables in `src/base/index.ts` |
| 84 | +4. Auto-imports become available for use in Nuxt applications |
| 85 | + |
| 86 | +### Testing |
| 87 | +- Uses Vitest for unit testing |
| 88 | +- Test fixtures in `test/fixtures/` for integration testing |
| 89 | +- ESLint configuration extends `@lenne.tech/eslint-config-vue` |
| 90 | + |
| 91 | +## Important Notes |
| 92 | + |
| 93 | +- Node.js >= 22 and npm >= 10 required |
| 94 | +- The module exits after type generation (5 second timeout) when `generateTypes` is enabled |
| 95 | +- WebSocket URL is automatically derived from `gqlHost` (https → wss, http → ws) |
| 96 | +- Built for ESM environments with proper transpilation handling for problematic dependencies |
0 commit comments