also looking at this
Deploy: uniform auth session model (main → production)
#7
282 files
+3028
-64856
| @@ -1,575 +0,0 @@ | ||
| 1 | # Build a Frontend | |
| 2 | ||
| 3 | This tutorial will guide you through building a frontend application with Stacks. You will learn how to create components using STX (Stacks Template Syntax), style them with Headwind CSS utilities, manage state, and set up routing. | |
| 4 | ||
| 5 | ## Stacks UI Engine | |
| 6 | ||
| 7 | The Stacks UI engine is responsible for rendering the UI of your application. It is designed to be framework-agnostic, meaning that the built results can be used with any JavaScript or TypeScript framework. | |
| 8 | ||
| 9 | The UI engine handles two core responsibilities: | |
| 10 | ||
| 11 | 1. **Rendering the Application** - Your main web application | |
| 12 | 2. **Rendering the Documentation** - Your docs site (powered by BunPress/VitePress) | |
| 13 | ||
| 14 | ## Creating Components with STX | |
| 15 | ||
| 16 | STX (Stacks Template Syntax) is a simple, HTML-like syntax for building components. Components live in the `resources/components/` directory. | |
| 17 | ||
| 18 | ### Basic Component Structure | |
| 19 | ||
| 20 | An STX component consists of three parts: script, template, and optional styles. | |
| 21 | ||
| 22 | ```html | |
| 23 | <!-- resources/components/Greeting.stx --> | |
| 24 | <script server> | |
| 25 | // Props - values passed from parent components | |
| 26 | const name = props.name || 'World' | |
| 27 | const showTime = props.showTime || false | |
| 28 | ||
| 29 | // Computed values | |
| 30 | const greeting = `Hello, ${name}!` | |
| 31 | const currentTime = new Date().toLocaleTimeString() | |
| 32 | </script> | |
| 33 | ||
| 34 | <div class="greeting-card"> | |
| 35 | <h1>{{ greeting }}</h1> | |
| 36 | ||
| 37 | @if(showTime) | |
| 38 | <p class="time">Current time: {{ currentTime }}</p> | |
| 39 | @endif | |
| 40 | </div> | |
| 41 | ||
| 42 | <style scoped> | |
| 43 | .greeting-card { | |
| 44 | padding: 1rem; | |
| 45 | border-radius: 0.5rem; | |
| 46 | background: #f8f9fa; | |
| 47 | } | |
| 48 | ||
| 49 | .time { | |
| 50 | color: #6c757d; | |
| 51 | font-size: 0.875rem; | |
| 52 | } | |
| 53 | </style> | |
| 54 | ``` | |
| 55 | ||
| 56 | ### Using Props | |
| 57 | ||
| 58 | Props allow you to pass data from parent to child components: | |
| 59 | ||
| 60 | ```html | |
| 61 | <!-- resources/components/Button.stx --> | |
| 62 | <script server> | |
| 63 | // Define props with defaults | |
| 64 | const variant = props.variant || 'solid' // 'solid' | 'outline' | |
| 65 | const color = props.color || 'blue' // 'blue' | 'slate' | 'white' | |
| 66 | const href = props.href || '' | |
| 67 | const customClass = props.customClass || '' | |
| 68 | ||
| 69 | // Style mappings | |
| 70 | const baseStyles = 'inline-flex items-center justify-center rounded-full py-2 px-4 text-sm font-semibold' | |
| 71 | ||
| 72 | const variantStyles = { | |
| 73 | solid: { | |
| 74 | blue: 'bg-blue-600 text-white hover:bg-blue-500', | |
| 75 | slate: 'bg-slate-900 text-white hover:bg-slate-700', | |
| 76 | }, | |
| 77 | outline: { | |
| 78 | blue: 'ring-1 ring-blue-200 text-blue-700 hover:ring-blue-300', | |
| 79 | slate: 'ring-1 ring-slate-200 text-slate-700 hover:ring-slate-300', | |
| 80 | }, | |
| 81 | } | |
| 82 | ||
| 83 | function getClassName() { | |
| 84 | return `${baseStyles} ${variantStyles[variant]?.[color] || ''} ${customClass}` | |
| 85 | } | |
| 86 | </script> | |
| 87 | ||
| 88 | @if(!href) | |
| 89 | <button class="{{ }} getClassName()"> | |
| 90 | <slot /> | |
| 91 | </button> | |
| 92 | @else | |
| 93 | <a href="{{ href }}" class="{{ }} getClassName()"> | |
| 94 | <slot /> | |
| 95 | </a> | |
| 96 | @endif | |
| 97 | ``` | |
| 98 | ||
| 99 | Using the component: | |
| 100 | ||
| 101 | ```html | |
| 102 | <!-- In another component or view --> | |
| 103 | <Button variant="solid" color="blue">Click Me</Button> | |
| 104 | <Button variant="outline" color="slate" href="/about">Learn More</Button> | |
| 105 | ``` | |
| 106 | ||
| 107 | ### Using Slots | |
| 108 | ||
| 109 | Slots allow you to pass content into components: | |
| 110 | ||
| 111 | ```html | |
| 112 | <!-- resources/components/Card.stx --> | |
| 113 | <script server> | |
| 114 | const title = props.title || '' | |
| 115 | </script> | |
| 116 | ||
| 117 | <div class="p-6 bg-white rounded-lg shadow-md card"> | |
| 118 | @if(title) | |
| 119 | <h2 class="mb-4 font-bold text-xl">{{ title }}</h2> | |
| 120 | @endif | |
| 121 | ||
| 122 | <div class="card-content"> | |
| 123 | <slot /> | |
| 124 | </div> | |
| 125 | ||
| 126 | @if(slots.footer) | |
| 127 | <div class="mt-4 pt-4 border-t card-footer"> | |
| 128 | <slot name="footer" /> | |
| 129 | </div> | |
| 130 | @endif | |
| 131 | </div> | |
| 132 | ``` | |
| 133 | ||
| 134 | Using named slots: | |
| 135 | ||
| 136 | ```html | |
| 137 | <Card title="My Card"> | |
| 138 | <p>This is the main content.</p> | |
| 139 | ||
| 140 | <template #footer> | |
| 141 | <Button>Save</Button> | |
| 142 | </template> | |
| 143 | </Card> | |
| 144 | ``` | |
| 145 | ||
| 146 | ### Conditionals and Loops | |
| 147 | ||
| 148 | STX provides Blade-like directives for control flow: | |
| 149 | ||
| 150 | ```html | |
| 151 | <script server> | |
| 152 | const items = props.items || [] | |
| 153 | const showEmpty = props.showEmpty || true | |
| 154 | </script> | |
| 155 | ||
| 156 | <ul class="item-list"> | |
| 157 | @if(items.length > 0) | |
| 158 | @for(item of items) | |
| 159 | <li class="item"> | |
| 160 | {{ item.name }} | |
| 161 | ||
| 162 | @if(item.isNew) | |
| 163 | <span class="badge">New</span> | |
| 164 | @endif | |
| 165 | </li> | |
| 166 | @endfor | |
| 167 | @elseif(showEmpty) | |
| 168 | <li class="empty">No items found</li> | |
| 169 | @endif | |
| 170 | </ul> | |
| 171 | ``` | |
| 172 | ||
| 173 | ## Styling with Headwind | |
| 174 | ||
| 175 | Stacks uses Headwind, a utility-first CSS framework similar to Tailwind CSS. You can use utility classes directly in your templates. | |
| 176 | ||
| 177 | ### Common Utility Classes | |
| 178 | ||
| 179 | ```html | |
| 180 | <!-- Layout --> | |
| 181 | <div class="flex items-center justify-between"> | |
| 182 | <div class="grid gap-4 grid-cols-3"> | |
| 183 | <!-- Grid items --> | |
| 184 | </div> | |
| 185 | </div> | |
| 186 | ||
| 187 | <!-- Spacing --> | |
| 188 | <div class="m-2 mb-4 mt-8 p-4 px-6 py-3"> | |
| 189 | <!-- Content with padding and margin --> | |
| 190 | </div> | |
| 191 | ||
| 192 | <!-- Typography --> | |
| 193 | <h1 class="font-bold text-3xl text-gray-900">Title</h1> | |
| 194 | <p class="leading-relaxed text-gray-600 text-sm">Body text</p> | |
| 195 | ||
| 196 | <!-- Colors --> | |
| 197 | <div class="text-white bg-blue-500"> | |
| 198 | <span class="text-blue-200">Colored text</span> | |
| 199 | </div> | |
| 200 | ||
| 201 | <!-- Borders and Shadows --> | |
| 202 | <div class="border border-gray-200 rounded-lg shadow-md"> | |
| 203 | <!-- Content --> | |
| 204 | </div> | |
| 205 | ||
| 206 | <!-- Responsive --> | |
| 207 | <div class="w-full md:w-1/2 lg:w-1/3"> | |
| 208 | <!-- Responsive width --> | |
| 209 | </div> | |
| 210 | ||
| 211 | <!-- Dark Mode --> | |
| 212 | <div class="text-gray-900 dark:text-white bg-white dark:bg-gray-900"> | |
| 213 | <!-- Dark mode support --> | |
| 214 | </div> | |
| 215 | ||
| 216 | <!-- Hover and Focus States --> | |
| 217 | <button class="bg-blue-500 hover:bg-blue-600 focus:ring-2 focus:ring-blue-300"> | |
| 218 | Hover me | |
| 219 | </button> | |
| 220 | ``` | |
| 221 | ||
| 222 | ### Using Icons | |
| 223 | ||
| 224 | Stacks supports icon classes using the `i-` prefix: | |
| 225 | ||
| 226 | ```html | |
| 227 | <i class="h-6 w-6 text-gray-500 i-hugeicons-outline-book-open"></i> | |
| 228 | <i class="h-5 w-5 text-red-500 i-hugeicons-outline-heart"></i> | |
| 229 | ``` | |
| 230 | ||
| 231 | ## State Management | |
| 232 | ||
| 233 | ### Local Component State | |
| 234 | ||
| 235 | For simple state within a component, use the script section: | |
| 236 | ||
| 237 | ```html | |
| 238 | <script server> | |
| 239 | let count = 0 | |
| 240 | ||
| 241 | function increment() { | |
| 242 | count++ | |
| 243 | } | |
| 244 | ||
| 245 | function decrement() { | |
| 246 | count-- | |
| 247 | } | |
| 248 | </script> | |
| 249 | ||
| 250 | <div class="counter"> | |
| 251 | <button onclick="decrement()">-</button> | |
| 252 | <span>{{ count }}</span> | |
| 253 | <button onclick="increment()">+</button> | |
| 254 | </div> | |
| 255 | ``` | |
| 256 | ||
| 257 | ### Reactive State | |
| 258 | ||
| 259 | For reactive state that updates the UI: | |
| 260 | ||
| 261 | ```html | |
| 262 | <script server> | |
| 263 | import { ref, computed } from '@stacksjs/reactivity' | |
| 264 | ||
| 265 | const count = ref(0) | |
| 266 | const doubled = computed(() => count.value * 2) | |
| 267 | ||
| 268 | function increment() { | |
| 269 | count.value++ | |
| 270 | } | |
| 271 | </script> | |
| 272 | ||
| 273 | <div class="counter"> | |
| 274 | <p>Count: {{ count.value }}</p> | |
| 275 | <p>Doubled: {{ doubled.value }}</p> | |
| 276 | <button onclick="increment()">Increment</button> | |
| 277 | </div> | |
| 278 | ``` | |
| 279 | ||
| 280 | ### Shared State | |
| 281 | ||
| 282 | For state shared across components, create a store: | |
| 283 | ||
| 284 | ```typescript | |
| 285 | // resources/functions/store.ts | |
| 286 | import { reactive } from '@stacksjs/reactivity' | |
| 287 | ||
| 288 | export const store = reactive({ | |
| 289 | user: null, | |
| 290 | isAuthenticated: false, | |
| 291 | theme: 'light', | |
| 292 | }) | |
| 293 | ||
| 294 | export function setUser(user) { | |
| 295 | store.user = user | |
| 296 | store.isAuthenticated = !!user | |
| 297 | } | |
| 298 | ||
| 299 | export function toggleTheme() { | |
| 300 | store.theme = store.theme === 'light' ? 'dark' : 'light' | |
| 301 | } | |
| 302 | ``` | |
| 303 | ||
| 304 | Using the store in components: | |
| 305 | ||
| 306 | ```html | |
| 307 | <script server> | |
| 308 | import { store, toggleTheme } from '../functions/store' | |
| 309 | </script> | |
| 310 | ||
| 311 | <div class="theme-toggle"> | |
| 312 | <span>Current theme: {{ store.theme }}</span> | |
| 313 | <button onclick="toggleTheme()">Toggle Theme</button> | |
| 314 | </div> | |
| 315 | ``` | |
| 316 | ||
| 317 | ## Routing | |
| 318 | ||
| 319 | Stacks supports two routing strategies for your frontend: | |
| 320 | ||
| 321 | ### File-based Routing (Default) | |
| 322 | ||
| 323 | With file-based routing, your file structure determines your routes. Files in `resources/views/` automatically become routes. | |
| 324 | ||
| 325 | ``` | |
| 326 | resources/views/ | |
| 327 | ├── index.stx # / | |
| 328 | ├── about.stx # /about | |
| 329 | ├── contact.stx # /contact | |
| 330 | ├── blog/ | |
| 331 | │ ├── index.stx # /blog | |
| 332 | │ └── [slug].stx # /blog/:slug (dynamic route) | |
| 333 | └── dashboard/ | |
| 334 | ├── index.stx # /dashboard | |
| 335 | └── settings.stx # /dashboard/settings | |
| 336 | ``` | |
| 337 | ||
| 338 | #### Dynamic Routes | |
| 339 | ||
| 340 | Use square brackets for dynamic segments: | |
| 341 | ||
| 342 | ```html | |
| 343 | <!-- resources/views/blog/[slug].stx --> | |
| 344 | <script server> | |
| 345 | const slug = params.slug | |
| 346 | // Fetch blog post using slug | |
| 347 | </script> | |
| 348 | ||
| 349 | <article> | |
| 350 | <h1>Blog Post: {{ slug }}</h1> | |
| 351 | </article> | |
| 352 | ``` | |
| 353 | ||
| 354 | ### Laravel-like Routing | |
| 355 | ||
| 356 | For more control, use explicit route definitions: | |
| 357 | ||
| 358 | ```typescript | |
| 359 | // routes/web.ts | |
| 360 | import { route } from '@stacksjs/router' | |
| 361 | ||
| 362 | route.get('/', 'HomeController@index') | |
| 363 | route.get('/about', 'AboutController@show') | |
| 364 | route.get('/blog/:slug', 'BlogController@show') | |
| 365 | route.get('/dashboard', 'DashboardController@index').middleware('auth') | |
| 366 | ``` | |
| 367 | ||
| 368 | ### Navigation | |
| 369 | ||
| 370 | Use the Link component or standard anchor tags: | |
| 371 | ||
| 372 | ```html | |
| 373 | <!-- Using anchor tags with utility classes --> | |
| 374 | <nav class="flex gap-4"> | |
| 375 | <a href="/" class="text-blue-600 hover:underline">Home</a> | |
| 376 | <a href="/about" class="text-blue-600 hover:underline">About</a> | |
| 377 | <a href="/contact" class="text-blue-600 hover:underline">Contact</a> | |
| 378 | </nav> | |
| 379 | ``` | |
| 380 | ||
| 381 | ## Layouts | |
| 382 | ||
| 383 | Create reusable layouts for consistent page structure: | |
| 384 | ||
| 385 | ```html | |
| 386 | <!-- resources/layouts/Default.stx --> | |
| 387 | <script server> | |
| 388 | const title = props.title || 'My App' | |
| 389 | </script> | |
| 390 | ||
| 391 | <!DOCTYPE html> | |
| 392 | <html lang="en"> | |
| 393 | <head> | |
| 394 | <meta charset="UTF-8"> | |
| 395 | <meta name="viewport" content="width=device-width, initial-scale=1.0"> | |
| 396 | <title>{{ title }}</title> | |
| 397 | </head> | |
| 398 | <body class="min-h-screen bg-gray-50 dark:bg-gray-900"> | |
| 399 | <header class="bg-white dark:bg-gray-800 shadow"> | |
| 400 | <nav class="mx-auto px-4 py-4 max-w-7xl"> | |
| 401 | <Logo /> | |
| 402 | <!-- Navigation items --> | |
| 403 | </nav> | |
| 404 | </header> | |
| 405 | ||
| 406 | <main class="mx-auto px-4 py-8 max-w-7xl"> | |
| 407 | <slot /> | |
| 408 | </main> | |
| 409 | ||
| 410 | <footer class="py-8 bg-gray-100 dark:bg-gray-800"> | |
| 411 | <div class="mx-auto px-4 max-w-7xl text-center text-gray-600"> | |
| 412 | © 2024 My App. All rights reserved. | |
| 413 | </div> | |
| 414 | </footer> | |
| 415 | </body> | |
| 416 | </html> | |
| 417 | ``` | |
| 418 | ||
| 419 | Using the layout in a view: | |
| 420 | ||
| 421 | ```html | |
| 422 | <!-- resources/views/index.stx --> | |
| 423 | <script server> | |
| 424 | layout = 'Default' | |
| 425 | </script> | |
| 426 | ||
| 427 | <div class="space-y-8"> | |
| 428 | <HelloWorld /> | |
| 429 | ||
| 430 | <section> | |
| 431 | <h2 class="mb-4 font-bold text-2xl">Welcome to My App</h2> | |
| 432 | <p class="text-gray-600">Build amazing things with Stacks.</p> | |
| 433 | </section> | |
| 434 | </div> | |
| 435 | ``` | |
| 436 | ||
| 437 | ## Complete Example: Task Manager | |
| 438 | ||
| 439 | Let us build a simple task manager to demonstrate all concepts: | |
| 440 | ||
| 441 | ```html | |
| 442 | <!-- resources/components/TaskItem.stx --> | |
| 443 | <script server> | |
| 444 | const task = props.task | |
| 445 | const onToggle = props.onToggle | |
| 446 | const onDelete = props.onDelete | |
| 447 | </script> | |
| 448 | ||
| 449 | <li class="flex gap-3 items-center p-3 bg-white rounded-lg shadow-sm"> | |
| 450 | <input | |
| 451 | type="checkbox" | |
| 452 | checked="{{ task.completed }}" | |
| 453 | onchange="onToggle(task.id)" | |
| 454 | class="h-5 w-5 border-gray-300 rounded" | |
| 455 | /> | |
| 456 | ||
| 457 | <span class="flex-1 text-gray-400' : ? 'line-through 'text-gray-900' {{ }} task.completed"> | |
| 458 | {{ task.title }} | |
| 459 | </span> | |
| 460 | ||
| 461 | <button | |
| 462 | onclick="onDelete(task.id)" | |
| 463 | class="text-red-500 hover:text-red-700" | |
| 464 | > | |
| 465 | <i class="h-5 w-5 i-hugeicons-outline-trash"></i> | |
| 466 | </button> | |
| 467 | </li> | |
| 468 | ``` | |
| 469 | ||
| 470 | ```html | |
| 471 | <!-- resources/components/TaskList.stx --> | |
| 472 | <script server> | |
| 473 | import { ref } from '@stacksjs/reactivity' | |
| 474 | ||
| 475 | const tasks = ref([ | |
| 476 | { id: 1, title: 'Learn Stacks', completed: false }, | |
| 477 | { id: 2, title: 'Build an app', completed: false }, | |
| 478 | { id: 3, title: 'Deploy to production', completed: false }, | |
| 479 | ]) | |
| 480 | ||
| 481 | const newTaskTitle = ref('') | |
| 482 | ||
| 483 | function addTask() { | |
| 484 | if (newTaskTitle.value.trim()) { | |
| 485 | tasks.value.push({ | |
| 486 | id: Date.now(), | |
| 487 | title: newTaskTitle.value, | |
| 488 | completed: false, | |
| 489 | }) | |
| 490 | newTaskTitle.value = '' | |
| 491 | } | |
| 492 | } | |
| 493 | ||
| 494 | function toggleTask(id) { | |
| 495 | const task = tasks.value.find(t => t.id === id) | |
| 496 | if (task) { | |
| 497 | task.completed = !task.completed | |
| 498 | } | |
| 499 | } | |
| 500 | ||
| 501 | function deleteTask(id) { | |
| 502 | tasks.value = tasks.value.filter(t => t.id !== id) | |
| 503 | } | |
| 504 | ||
| 505 | const completedCount = computed(() => | |
| 506 | tasks.value.filter(t => t.completed).length | |
| 507 | ) | |
| 508 | </script> | |
| 509 | ||
| 510 | <div class="mx-auto p-6 max-w-md"> | |
| 511 | <h1 class="mb-6 font-bold text-2xl">Task Manager</h1> | |
| 512 | ||
| 513 | <!-- Add Task Form --> | |
| 514 | <div class="flex gap-2 mb-6"> | |
| 515 | <input | |
| 516 | type="text" | |
| 517 | value="{{ newTaskTitle.value }}" | |
| 518 | oninput="newTaskTitle.value = event.target.value" | |
| 519 | placeholder="Add a new task..." | |
| 520 | class="flex-1 px-4 py-2 border border-gray-300 rounded-lg focus:ring-2 focus:ring-blue-500" | |
| 521 | /> | |
| 522 | <Button variant="solid" color="blue" onclick="addTask()"> | |
| 523 | Add | |
| 524 | </Button> | |
| 525 | </div> | |
| 526 | ||
| 527 | <!-- Task List --> | |
| 528 | <ul class="space-y-2"> | |
| 529 | @for(task of tasks.value) | |
| 530 | <TaskItem | |
| 531 | task="{{ task }}" | |
| 532 | onToggle="{{ toggleTask }}" | |
| 533 | onDelete="{{ deleteTask }}" | |
| 534 | /> | |
| 535 | @endfor | |
| 536 | </ul> | |
| 537 | ||
| 538 | <!-- Summary --> | |
| 539 | <p class="mt-4 text-gray-600 text-sm"> | |
| 540 | {{ completedCount.value }} of {{ tasks.value.length }} tasks completed | |
| 541 | </p> | |
| 542 | </div> | |
| 543 | ``` | |
| 544 | ||
| 545 | ## Configuration | |
| 546 | ||
| 547 | Configure your STX components in `stx.config.ts`: | |
| 548 | ||
| 549 | ```typescript | |
| 550 | // stx.config.ts | |
| 551 | export default { | |
| 552 | // Components directory - for user-defined components | |
| 553 | componentsDir: 'resources/components', | |
| 554 | ||
| 555 | // Layouts directory - for layout templates | |
| 556 | layoutsDir: 'resources/layouts', | |
| 557 | ||
| 558 | // Partials directory - for partial templates | |
| 559 | partialsDir: 'resources/partials', | |
| 560 | } | |
| 561 | ``` | |
| 562 | ||
| 563 | ## Next Steps | |
| 564 | ||
| 565 | Now that you know how to build frontends with Stacks, continue to: | |
| 566 | ||
| 567 | - [Build an API](/bootcamp/api) - Create backend endpoints for your frontend | |
| 568 | - [Authentication How-To](/bootcamp/how-to/authentication) - Add user authentication | |
| 569 | - [Testing How-To](/bootcamp/how-to/testing) - Write tests for your components | |
| 570 | ||
| 571 | ## Related Documentation | |
| 572 | ||
| 573 | - [Components Guide](/basics/components) | |
| 574 | - [Views Guide](/basics/views) | |
| 575 | - [Routing Guide](/basics/routing) | |