also looking at this
Deploy: uniform auth session model (main → production)
#7
282 files
+3028
-64856
| @@ -1,504 +0,0 @@ | ||
| 1 | # IDE Setup | |
| 2 | ||
| 3 | This guide covers setting up your IDE for optimal Stacks development, including recommended extensions, configurations, and productivity tips. | |
| 4 | ||
| 5 | ## Recommended IDEs | |
| 6 | ||
| 7 | Stacks works well with any modern IDE, but we recommend: | |
| 8 | ||
| 9 | - **VS Code** - Primary recommendation | |
| 10 | - **Cursor** - AI-powered fork of VS Code | |
| 11 | - **WebStorm** - JetBrains IDE | |
| 12 | - **Zed** - High-performance editor | |
| 13 | ||
| 14 | ## VS Code Setup | |
| 15 | ||
| 16 | ### Essential Extensions | |
| 17 | ||
| 18 | Install these extensions for the best experience: | |
| 19 | ||
| 20 | ```bash | |
| 21 | # Install via command line | |
| 22 | code --install-extension dbaeumer.vscode-eslint | |
| 23 | code --install-extension esbenp.prettier-vscode | |
| 24 | code --install-extension bradlc.vscode-tailwindcss | |
| 25 | code --install-extension vue.volar | |
| 26 | code --install-extension oven.bun-vscode | |
| 27 | ``` | |
| 28 | ||
| 29 | #### Recommended Extensions List | |
| 30 | ||
| 31 | 1. **ESLint** (`dbaeumer.vscode-eslint`) - Linting | |
| 32 | 2. **Prettier** (`esbenp.prettier-vscode`) - Code formatting | |
| 33 | 3. **Tailwind CSS IntelliSense** (`bradlc.vscode-tailwindcss`) - CSS autocomplete | |
| 34 | 4. **Volar** (`vue.volar`) - Vue/TypeScript support | |
| 35 | 5. **Bun** (`oven.bun-vscode`) - Bun runtime support | |
| 36 | 6. **TypeScript Vue Plugin (Volar)** (`vue.vscode-typescript-vue-plugin`) - Type support | |
| 37 | 7. **GitLens** (`eamodio.gitlens`) - Git integration | |
| 38 | 8. **Error Lens** (`usernamehw.errorlens`) - Inline error display | |
| 39 | 9. **Auto Rename Tag** (`formulahendry.auto-rename-tag`) - HTML tag editing | |
| 40 | 10. **Path Intellisense** (`christian-kohler.path-intellisense`) - Path autocomplete | |
| 41 | ||
| 42 | ### VS Code Settings | |
| 43 | ||
| 44 | Create or update `.vscode/settings.json`: | |
| 45 | ||
| 46 | ```json | |
| 47 | { | |
| 48 | // Editor | |
| 49 | "editor.formatOnSave": true, | |
| 50 | "editor.defaultFormatter": "esbenp.prettier-vscode", | |
| 51 | "editor.codeActionsOnSave": { | |
| 52 | "source.fixAll.eslint": "explicit", | |
| 53 | "source.organizeImports": "explicit" | |
| 54 | }, | |
| 55 | "editor.tabSize": 2, | |
| 56 | "editor.insertSpaces": true, | |
| 57 | "editor.detectIndentation": false, | |
| 58 | "editor.wordWrap": "on", | |
| 59 | "editor.linkedEditing": true, | |
| 60 | "editor.bracketPairColorization.enabled": true, | |
| 61 | "editor.guides.bracketPairs": true, | |
| 62 | ||
| 63 | // Files | |
| 64 | "files.trimTrailingWhitespace": true, | |
| 65 | "files.insertFinalNewline": true, | |
| 66 | "files.trimFinalNewlines": true, | |
| 67 | "files.associations": { | |
| 68 | "*.stx": "vue" | |
| 69 | }, | |
| 70 | ||
| 71 | // TypeScript | |
| 72 | "typescript.preferences.importModuleSpecifier": "relative", | |
| 73 | "typescript.suggest.autoImports": true, | |
| 74 | "typescript.updateImportsOnFileMove.enabled": "always", | |
| 75 | ||
| 76 | // ESLint | |
| 77 | "eslint.validate": [ | |
| 78 | "javascript", | |
| 79 | "typescript", | |
| 80 | "vue" | |
| 81 | ], | |
| 82 | "eslint.useFlatConfig": true, | |
| 83 | ||
| 84 | // Tailwind CSS | |
| 85 | "tailwindCSS.includeLanguages": { | |
| 86 | "vue": "html", | |
| 87 | "stx": "html" | |
| 88 | }, | |
| 89 | "tailwindCSS.experimental.classRegex": [ | |
| 90 | ["class\\s*=\\s*[\"']([^\"']*)[\"']", "([^\"'\\s]*)"] | |
| 91 | ], | |
| 92 | ||
| 93 | // Vue / Volar | |
| 94 | "[vue]": { | |
| 95 | "editor.defaultFormatter": "esbenp.prettier-vscode" | |
| 96 | }, | |
| 97 | ||
| 98 | // JavaScript/TypeScript | |
| 99 | "[javascript]": { | |
| 100 | "editor.defaultFormatter": "esbenp.prettier-vscode" | |
| 101 | }, | |
| 102 | "[typescript]": { | |
| 103 | "editor.defaultFormatter": "esbenp.prettier-vscode" | |
| 104 | }, | |
| 105 | "[json]": { | |
| 106 | "editor.defaultFormatter": "esbenp.prettier-vscode" | |
| 107 | }, | |
| 108 | ||
| 109 | // Search | |
| 110 | "search.exclude": { | |
| 111 | "**/node*modules": true, | |
| 112 | "**/dist": true, | |
| 113 | "**/storage/framework": true, | |
| 114 | "**/.git": true, | |
| 115 | "**/bun.lockb": true | |
| 116 | }, | |
| 117 | ||
| 118 | // Explorer | |
| 119 | "explorer.fileNesting.enabled": true, | |
| 120 | "explorer.fileNesting.patterns": { | |
| 121 | "*.ts": "${capture}.test.ts, ${capture}.spec.ts", | |
| 122 | "*.vue": "${capture}.test.ts, ${capture}.spec.ts", | |
| 123 | "package.json": "package-lock.json, bun.lockb, yarn.lock, pnpm-lock.yaml, .npmrc", | |
| 124 | "tsconfig.json": "tsconfig.*.json" | |
| 125 | } | |
| 126 | } | |
| 127 | ``` | |
| 128 | ||
| 129 | ### Launch Configuration | |
| 130 | ||
| 131 | Create `.vscode/launch.json` for debugging: | |
| 132 | ||
| 133 | ```json | |
| 134 | { | |
| 135 | "version": "0.2.0", | |
| 136 | "configurations": [ | |
| 137 | { | |
| 138 | "type": "bun", | |
| 139 | "request": "launch", | |
| 140 | "name": "Debug Stacks App", | |
| 141 | "program": "${workspaceFolder}/buddy", | |
| 142 | "args": ["dev"], | |
| 143 | "cwd": "${workspaceFolder}", | |
| 144 | "env": { | |
| 145 | "NODE*ENV": "development" | |
| 146 | } | |
| 147 | }, | |
| 148 | { | |
| 149 | "type": "bun", | |
| 150 | "request": "launch", | |
| 151 | "name": "Run Tests", | |
| 152 | "program": "${workspaceFolder}/buddy", | |
| 153 | "args": ["test"], | |
| 154 | "cwd": "${workspaceFolder}" | |
| 155 | }, | |
| 156 | { | |
| 157 | "type": "bun", | |
| 158 | "request": "launch", | |
| 159 | "name": "Debug Current File", | |
| 160 | "program": "${file}", | |
| 161 | "cwd": "${workspaceFolder}" | |
| 162 | } | |
| 163 | ] | |
| 164 | } | |
| 165 | ``` | |
| 166 | ||
| 167 | ### Tasks Configuration | |
| 168 | ||
| 169 | Create `.vscode/tasks.json`: | |
| 170 | ||
| 171 | ```json | |
| 172 | { | |
| 173 | "version": "2.0.0", | |
| 174 | "tasks": [ | |
| 175 | { | |
| 176 | "label": "dev", | |
| 177 | "type": "shell", | |
| 178 | "command": "bun run dev", | |
| 179 | "problemMatcher": [], | |
| 180 | "group": { | |
| 181 | "kind": "build", | |
| 182 | "isDefault": true | |
| 183 | } | |
| 184 | }, | |
| 185 | { | |
| 186 | "label": "build", | |
| 187 | "type": "shell", | |
| 188 | "command": "bun run build", | |
| 189 | "problemMatcher": [] | |
| 190 | }, | |
| 191 | { | |
| 192 | "label": "test", | |
| 193 | "type": "shell", | |
| 194 | "command": "bun test", | |
| 195 | "problemMatcher": [] | |
| 196 | }, | |
| 197 | { | |
| 198 | "label": "lint", | |
| 199 | "type": "shell", | |
| 200 | "command": "bun run lint", | |
| 201 | "problemMatcher": ["$eslint-stylish"] | |
| 202 | }, | |
| 203 | { | |
| 204 | "label": "typecheck", | |
| 205 | "type": "shell", | |
| 206 | "command": "bun run typecheck", | |
| 207 | "problemMatcher": ["$tsc"] | |
| 208 | } | |
| 209 | ] | |
| 210 | } | |
| 211 | ``` | |
| 212 | ||
| 213 | ### Snippets | |
| 214 | ||
| 215 | Create `.vscode/stacks.code-snippets`: | |
| 216 | ||
| 217 | ```json | |
| 218 | { | |
| 219 | "Stacks Action": { | |
| 220 | "prefix": "action", | |
| 221 | "body": [ | |
| 222 | "import type { RequestInstance } from '@stacksjs/types'", | |
| 223 | "import { Action } from '@stacksjs/actions'", | |
| 224 | "import { response } from '@stacksjs/router'", | |
| 225 | "", | |
| 226 | "export default new Action({", | |
| 227 | " name: '${1:ActionName}',", | |
| 228 | " description: '${2:Description}',", | |
| 229 | " method: '${3|GET,POST,PUT,PATCH,DELETE|}',", | |
| 230 | "", | |
| 231 | " async handle(request: RequestInstance) {", | |
| 232 | " $0", | |
| 233 | " return response.json({ success: true })", | |
| 234 | " },", | |
| 235 | "})" | |
| 236 | ], | |
| 237 | "description": "Create a Stacks action" | |
| 238 | }, | |
| 239 | ||
| 240 | "Stacks Model": { | |
| 241 | "prefix": "model", | |
| 242 | "body": [ | |
| 243 | "import { Model } from '@stacksjs/orm'", | |
| 244 | "", | |
| 245 | "export default new Model({", | |
| 246 | " name: '${1:ModelName}',", | |
| 247 | " table: '${2:table*name}',", | |
| 248 | "", | |
| 249 | " fields: {", | |
| 250 | " $0", | |
| 251 | " },", | |
| 252 | "})" | |
| 253 | ], | |
| 254 | "description": "Create a Stacks model" | |
| 255 | }, | |
| 256 | ||
| 257 | "Stacks Component": { | |
| 258 | "prefix": "component", | |
| 259 | "body": [ | |
| 260 | "<script setup lang=\"ts\">", | |
| 261 | "import { ref } from 'vue'", | |
| 262 | "", | |
| 263 | "const ${1:state} = ref($2)", | |
| 264 | "$0", | |
| 265 | "</script>", | |
| 266 | "", | |
| 267 | "<template>", | |
| 268 | " <div>", | |
| 269 | " ", | |
| 270 | " </div>", | |
| 271 | "</template>", | |
| 272 | "", | |
| 273 | "<style scoped>", | |
| 274 | "</style>" | |
| 275 | ], | |
| 276 | "description": "Create a Vue component" | |
| 277 | }, | |
| 278 | ||
| 279 | "Stacks Test": { | |
| 280 | "prefix": "test", | |
| 281 | "body": [ | |
| 282 | "import { describe, it, expect } from 'bun:test'", | |
| 283 | "", | |
| 284 | "describe('${1:TestName}', () => {", | |
| 285 | " it('${2:should do something}', () => {", | |
| 286 | " $0", | |
| 287 | " expect(true).toBe(true)", | |
| 288 | " })", | |
| 289 | "})" | |
| 290 | ], | |
| 291 | "description": "Create a test file" | |
| 292 | } | |
| 293 | } | |
| 294 | ``` | |
| 295 | ||
| 296 | ## Cursor Setup | |
| 297 | ||
| 298 | Cursor uses VS Code settings, so apply the same configuration above. Additionally: | |
| 299 | ||
| 300 | ### AI Configuration | |
| 301 | ||
| 302 | Create `.cursor/settings.json`: | |
| 303 | ||
| 304 | ```json | |
| 305 | { | |
| 306 | "cursor.chat.model": "claude-3.5-sonnet", | |
| 307 | "cursor.contextMode": "normal", | |
| 308 | "cursor.cpp.disabledLanguages": [], | |
| 309 | "cursor.chat.systemPrompt": "You are helping develop a Stacks.js application. Stacks uses Bun as the runtime, Vue for components, and provides a full-stack TypeScript framework. Follow Stacks conventions and best practices." | |
| 310 | } | |
| 311 | ``` | |
| 312 | ||
| 313 | ### Cursor Rules | |
| 314 | ||
| 315 | Create `.cursorrules`: | |
| 316 | ||
| 317 | ``` | |
| 318 | # Stacks Development Rules | |
| 319 | ||
| 320 | ## Technology Stack | |
| 321 | ||
| 322 | - Runtime: Bun | |
| 323 | - Framework: Stacks.js | |
| 324 | - Language: TypeScript | |
| 325 | - Frontend: Vue 3 with Composition API | |
| 326 | - Styling: Tailwind CSS | |
| 327 | - Database: SQLite/MySQL with custom ORM | |
| 328 | ||
| 329 | ## Conventions | |
| 330 | ||
| 331 | - Use TypeScript for all code | |
| 332 | - Prefer async/await over callbacks | |
| 333 | - Use named exports | |
| 334 | - Follow single-responsibility principle | |
| 335 | - Keep functions small and focused | |
| 336 | ||
| 337 | ## File Structure | |
| 338 | ||
| 339 | - Actions go in app/Actions/ | |
| 340 | - Models go in app/Models/ | |
| 341 | - Components go in resources/components/ | |
| 342 | - Tests go alongside source files with .test.ts extension | |
| 343 | ||
| 344 | ## Code Style | |
| 345 | ||
| 346 | - 2 spaces for indentation | |
| 347 | - Single quotes for strings | |
| 348 | - No semicolons (except where required) | |
| 349 | - Trailing commas in multiline | |
| 350 | ||
| 351 | ``` | |
| 352 | ||
| 353 | ## WebStorm Setup | |
| 354 | ||
| 355 | ### Enable Bun Support | |
| 356 | ||
| 357 | 1. Go to **Settings > Languages & Frameworks > Node.js** | |
| 358 | 2. Set Node interpreter to Bun | |
| 359 | ||
| 360 | ### Configure ESLint | |
| 361 | ||
| 362 | 1. Go to **Settings > Languages & Frameworks > JavaScript > Code Quality Tools > ESLint** | |
| 363 | 2. Select "Automatic ESLint configuration" | |
| 364 | ||
| 365 | ### Configure Prettier | |
| 366 | ||
| 367 | 1. Go to **Settings > Languages & Frameworks > JavaScript > Prettier** | |
| 368 | 2. Enable "Run on save" | |
| 369 | ||
| 370 | ### File Watchers | |
| 371 | ||
| 372 | Set up TypeScript compilation: | |
| 373 | ||
| 374 | 1. Go to **Settings > Tools > File Watchers** | |
| 375 | 2. Add TypeScript watcher with Bun | |
| 376 | ||
| 377 | ## Zed Setup | |
| 378 | ||
| 379 | ### Settings | |
| 380 | ||
| 381 | Create `~/.config/zed/settings.json`: | |
| 382 | ||
| 383 | ```json | |
| 384 | { | |
| 385 | "theme": "One Dark", | |
| 386 | "buffer*font*family": "JetBrains Mono", | |
| 387 | "buffer*font*size": 14, | |
| 388 | "format*on*save": "on", | |
| 389 | "languages": { | |
| 390 | "TypeScript": { | |
| 391 | "tab*size": 2, | |
| 392 | "formatter": "prettier" | |
| 393 | }, | |
| 394 | "Vue": { | |
| 395 | "tab*size": 2, | |
| 396 | "formatter": "prettier" | |
| 397 | } | |
| 398 | }, | |
| 399 | "lsp": { | |
| 400 | "typescript-language-server": { | |
| 401 | "initialization*options": { | |
| 402 | "preferences": { | |
| 403 | "importModuleSpecifierPreference": "relative" | |
| 404 | } | |
| 405 | } | |
| 406 | } | |
| 407 | } | |
| 408 | } | |
| 409 | ``` | |
| 410 | ||
| 411 | ## Common Configuration | |
| 412 | ||
| 413 | ### EditorConfig | |
| 414 | ||
| 415 | Create `.editorconfig` in your project root: | |
| 416 | ||
| 417 | ```ini | |
| 418 | root = true | |
| 419 | ||
| 420 | [*] | |
| 421 | charset = utf-8 | |
| 422 | indent*style = space | |
| 423 | indent*size = 2 | |
| 424 | end*of*line = lf | |
| 425 | insert*final*newline = true | |
| 426 | trim*trailing*whitespace = true | |
| 427 | ||
| 428 | [*.md] | |
| 429 | trim*trailing*whitespace = false | |
| 430 | ||
| 431 | [*.{yml,yaml}] | |
| 432 | indent*size = 2 | |
| 433 | ||
| 434 | [Makefile] | |
| 435 | indent*style = tab | |
| 436 | ``` | |
| 437 | ||
| 438 | ### Git Configuration | |
| 439 | ||
| 440 | Create `.gitattributes`: | |
| 441 | ||
| 442 | ``` | |
| 443 | ||
| 444 | * text=auto eol=lf | |
| 445 | ||
| 446 | *.{cmd,[cC][mM][dD]} text eol=crlf | |
| 447 | *.{bat,[bB][aA][tT]} text eol=crlf | |
| 448 | bun.lockb binary | |
| 449 | ``` | |
| 450 | ||
| 451 | ## Keyboard Shortcuts | |
| 452 | ||
| 453 | ### Recommended VS Code Shortcuts | |
| 454 | ||
| 455 | | Action | Windows/Linux | macOS | | |
| 456 | |--------|--------------|-------| | |
| 457 | | Go to File | `Ctrl+P` | `Cmd+P` | | |
| 458 | | Go to Symbol | `Ctrl+Shift+O` | `Cmd+Shift+O` | | |
| 459 | | Find in Files | `Ctrl+Shift+F` | `Cmd+Shift+F` | | |
| 460 | | Quick Fix | `Ctrl+.` | `Cmd+.` | | |
| 461 | | Rename Symbol | `F2` | `F2` | | |
| 462 | | Toggle Terminal | ``Ctrl+```|``Cmd+``` | | |
| 463 | | Run Task | `Ctrl+Shift+B` | `Cmd+Shift+B` | | |
| 464 | | Format Document | `Shift+Alt+F` | `Shift+Option+F` | | |
| 465 | ||
| 466 | ### Custom Keybindings | |
| 467 | ||
| 468 | Add to `keybindings.json`: | |
| 469 | ||
| 470 | ```json | |
| 471 | [ | |
| 472 | { | |
| 473 | "key": "ctrl+shift+t", | |
| 474 | "command": "workbench.action.tasks.runTask", | |
| 475 | "args": "test" | |
| 476 | }, | |
| 477 | { | |
| 478 | "key": "ctrl+shift+d", | |
| 479 | "command": "workbench.action.tasks.runTask", | |
| 480 | "args": "dev" | |
| 481 | } | |
| 482 | ] | |
| 483 | ``` | |
| 484 | ||
| 485 | ## Troubleshooting | |
| 486 | ||
| 487 | ### TypeScript Errors Not Showing | |
| 488 | ||
| 489 | 1. Restart the TypeScript server: `Cmd/Ctrl+Shift+P` > "TypeScript: Restart TS Server" | |
| 490 | 2. Check that Volar is enabled and Take Over Mode is configured | |
| 491 | ||
| 492 | ### ESLint Not Working | |
| 493 | ||
| 494 | 1. Ensure ESLint extension is installed | |
| 495 | 2. Check that `eslint.config.js` exists in project root | |
| 496 | 3. Run `bun install` to ensure dependencies are installed | |
| 497 | ||
| 498 | ### Slow Performance | |
| 499 | ||
| 500 | 1. Exclude `node_modules` and `dist` from search | |
| 501 | 2. Disable unused extensions | |
| 502 | 3. Enable "files.watcherExclude" for large directories | |
| 503 | ||
| 504 | This documentation covers setting up your IDE for Stacks development. Each configuration is designed for an optimal development experience. | |