-
Notifications
You must be signed in to change notification settings - Fork 2
Expand file tree
/
Copy path.cursorrules
More file actions
69 lines (57 loc) · 5.19 KB
/
.cursorrules
File metadata and controls
69 lines (57 loc) · 5.19 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
## Development Rules for landingpages Project
### Code Style & Quality
- **Formatting:** Use Prettier. Run `npm run prettier:fix` to format code automatically.
- **Linting:**
- Run `npm run lint:eslint` for ESLint checks (style, patterns).
- Run `npm run lint:types` for TypeScript type checking (`tsc --noEmit`).
- Run `npm run lint` for both.
- **Testing (Vitest):**
- Uses Vitest with the `jsdom` environment.
- Test files should be located in the `tests/` directory and follow the `*.test.ts` or `*.test.tsx` pattern.
- Run tests using `npm test` or `npm run test:watch` for watch mode.
- See `vitest.config.ts` for configuration.
- **Combined Check:** Run `npm run quality` to execute Prettier, Linters (ESLint + TSC), and Tests (using `npm test`).
- **TypeScript:** Adhere to TypeScript best practices. Avoid `any` types where possible. Ensure type declarations are accurate.
### Build Process
- **Bundler:** Webpack handles TypeScript compilation, CSS processing (Tailwind/PostCSS), and HTML processing.
- **Build Command:**
- Use `npm run build` for development builds (includes source maps).
- Use `npm run build:prod` for production builds (no source maps, content hashes in filenames).
- **Output:** Compiled assets are placed in the `dist/` directory.
- **HTML Processing:**
- All non-partial `.html` files within `src/` are automatically found (`glob`) and processed by `html-webpack-plugin`.
- `posthtml-loader` with `posthtml-include` is used *before* `html-loader` to handle `<include src="..."></include>` tags for HTML partials.
- Partials should reside in `src/partials/` and are excluded from direct `HtmlWebpackPlugin` processing.
- HTML minification is disabled via `HtmlWebpackPlugin` config.
- **Output Structure:** The directory structure within `src/` (for non-partial HTML) is mirrored in `dist/`.
- **CSS Processing:** Tailwind CSS is processed via `@tailwindcss/postcss` configured in `postcss.config.js`. CSS is extracted to `dist/styles/[name].[contenthash].css` (production) or `dist/styles/[name].css` (development) using `mini-css-extract-plugin`.
- **JS Processing:** TypeScript is compiled to `bundle.[contenthash].js` (production) or `bundle.js` (development).
- **Asset Paths:** Relative paths are used for assets (JS bundle, CSS files) in the generated HTML (`output.publicPath: 'auto'`).
- **Clean Build:** The `dist/` directory is cleaned before each build (`output.clean: true`).
- **JS Target:** TypeScript is compiled to `es2017` (defined in `tsconfig.json`), using `module: node16` and `moduleResolution: node16`.
### JavaScript Framework (Stimulus)
- **Framework:** Use Stimulus for client-side JavaScript interactivity.
- **Controller Location:** Stimulus controllers (TypeScript files) must reside within the `src/controllers/` directory or its subdirectories.
- **Controller Naming:** Follow the standard Stimulus naming convention based on the file path relative to `src/controllers/`. For a controller at `src/controllers/folder/modal_controller.ts`, the identifier is `folder--modal` (used as `data-controller="folder--modal"`). This mapping is handled by `@hotwired/stimulus-webpack-helpers`.
- **Global Access:** Access the Stimulus application instance via `window.Stimulus`. A global type declaration (`src/types/global.d.ts`) ensures TypeScript recognizes this.
### Styling & UI Features
- **Styling:** Use Tailwind CSS v4 utility classes.
- **Theme (Dark/Light Mode):**
- Enabled via `darkMode: 'class'` in `tailwind.config.js`.
- `@custom-variant dark (&:where(.dark, .dark *));` added to `main.css` (if needed by specific Tailwind/PostCSS versions).
- An inline script (`src/partials/theme-fouc-guard.html`, included via `<include>`) runs in the `<head>` to apply the correct theme class (`dark`) to `<html>` immediately, preventing FOUC.
- The script checks `localStorage` for a `theme` key ('dark' or 'light').
- If no `theme` key exists, it falls back to the user's OS preference (`prefers-color-scheme`).
- A Stimulus controller (`src/controllers/theme_controller.ts`) manages the toggle button, updates `localStorage`, and updates the button's text.
### Environment
- **Node.js Version:** Use the Node.js version specified in the `.nvmrc` file. Run `nvm use` in the project root to activate the correct version.
### File Structure
- `src/`: Contains all source code (`.ts`, `.html`, `.css`).
- `src/controllers/`: Contains Stimulus controller files.
- `src/partials/`: Contains reusable HTML partials (e.g., `theme-fouc-guard.html`).
- `src/styles/`: Contains source CSS files (e.g., `main.css`).
- `src/types/`: Contains custom TypeScript declaration files (e.g., `global.d.ts`).
- `tests/`: Contains Vitest test files (`*.test.ts`).
- `tests/controllers/`: Contains tests for Stimulus controllers.
- `dist/`: Contains the compiled output, mirroring the structure of `src/` for non-partial HTML files.
- **Root:** Configuration files (`package.json`, `webpack.config.js`, `tsconfig.json`, `tailwind.config.js`, `postcss.config.js`, `eslint.config.mjs`, `vitest.config.ts`, `.nvmrc`, `.cursorrules`, etc.) reside at the project root.