@boopkit/cap-web 0.1.1 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +131 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,131 @@
|
|
|
1
|
+
# @boopkit/cap-web
|
|
2
|
+
|
|
3
|
+
**Part of [Boop](https://www.npmjs.com/package/@boopkit/cli)** — a bootstrap platform for AI-first builders. `boop init` scaffolds a running Node/TypeScript web app from composable **capabilities**, each one bundling the code, dependencies, middleware wiring, and agent skills needed for a feature. You pick the capabilities; `boop add` handles the rest.
|
|
4
|
+
|
|
5
|
+
`cap-web` is the UI layer. It gives your Express app a Handlebars view engine, Tailwind CSS with a semantic-class convention, static asset serving, and a lightweight request logger — everything needed to render server-side pages with a clean HTML UI.
|
|
6
|
+
|
|
7
|
+
## What You Get
|
|
8
|
+
|
|
9
|
+
### Scaffold files
|
|
10
|
+
|
|
11
|
+
Copied into your project on install:
|
|
12
|
+
|
|
13
|
+
- `views/` — Handlebars templates (`home.hbs`, `about.hbs`, `404.hbs`) and `layouts/main.hbs`
|
|
14
|
+
- `public/` — static assets served at `/` (`css/`, `favicon.svg`)
|
|
15
|
+
- `styles/styles.css` — Tailwind input file with semantic class definitions using `@apply`
|
|
16
|
+
- `tailwind.config.ts` — Tailwind configuration
|
|
17
|
+
- `src/controllers/pages.ts` — example page controllers (`home`, `about`)
|
|
18
|
+
- `src/routes/pages.ts` — Express router mounting the example pages
|
|
19
|
+
- `reference/web-ui.ref.md` — reference doc describing the UI conventions
|
|
20
|
+
|
|
21
|
+
### Scripts added to `package.json`
|
|
22
|
+
|
|
23
|
+
| Script | Command |
|
|
24
|
+
|--------|---------|
|
|
25
|
+
| `tailwind:build` | `npx @tailwindcss/cli -i styles/styles.css -o public/css/style.css --minify` |
|
|
26
|
+
| `tailwind:watch` | `npx @tailwindcss/cli -i styles/styles.css -o public/css/style.css --watch` |
|
|
27
|
+
|
|
28
|
+
### Server hooks
|
|
29
|
+
|
|
30
|
+
Wired into `src/server.ts` at install time:
|
|
31
|
+
|
|
32
|
+
```ts
|
|
33
|
+
import { configureViewEngine, configureStatic, requestLogger } from '@boopkit/cap-web';
|
|
34
|
+
import pageRoutes from './routes/pages';
|
|
35
|
+
|
|
36
|
+
// ...
|
|
37
|
+
|
|
38
|
+
app.use(requestLogger()); // order 12 — logs method, URL, status, timing
|
|
39
|
+
configureViewEngine(app); // order 40 — Handlebars engine + layouts
|
|
40
|
+
configureStatic(app); // order 45 — serve ./public with cache headers
|
|
41
|
+
app.use(pageRoutes); // order 50 — mount the example pages
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Order numbers are the `preRoutes` phase ordering; other capabilities slot themselves around these (for example, `cap-api`'s error handler mounts after route handlers).
|
|
45
|
+
|
|
46
|
+
### Skills installed
|
|
47
|
+
|
|
48
|
+
- `design.web-ui-design.skill.md` — teaches agents the semantic-CSS convention and view-rendering patterns used in boop web apps.
|
|
49
|
+
|
|
50
|
+
### Post-install
|
|
51
|
+
|
|
52
|
+
Run `npm run tailwind:build` once after install to compile `styles/styles.css` into `public/css/style.css`. `boop status` reminds you of this.
|
|
53
|
+
|
|
54
|
+
## Requirements
|
|
55
|
+
|
|
56
|
+
**Other capabilities:** none — `cap-web` is self-contained.
|
|
57
|
+
|
|
58
|
+
**npm dependencies added to your project:**
|
|
59
|
+
|
|
60
|
+
- `express-handlebars` — view engine binding
|
|
61
|
+
- `tailwindcss` — utility-first CSS framework
|
|
62
|
+
- `@tailwindcss/cli` (devDependency) — CSS compilation
|
|
63
|
+
|
|
64
|
+
**Peer dependencies** (already provided by the `web-app` kernel):
|
|
65
|
+
|
|
66
|
+
- `express >=4.0.0`
|
|
67
|
+
- `express-handlebars >=7.0.0`
|
|
68
|
+
- `handlebars >=4.0.0`
|
|
69
|
+
|
|
70
|
+
**Environment variables:** none required. `NODE_ENV=production` enables a 1-day cache on static assets; otherwise caching is disabled.
|
|
71
|
+
|
|
72
|
+
## Usage
|
|
73
|
+
|
|
74
|
+
A page in a boop web app is three small files plus styles. Here's how to add one from scratch:
|
|
75
|
+
|
|
76
|
+
**1.** Create a view at `views/dashboard.hbs`:
|
|
77
|
+
|
|
78
|
+
```handlebars
|
|
79
|
+
<main class="dashboard-page">
|
|
80
|
+
<h1 class="page-title">Dashboard</h1>
|
|
81
|
+
<p class="page-subtitle">Welcome back, {{user.name}}.</p>
|
|
82
|
+
</main>
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
**2.** Add a controller in `src/controllers/pages.ts`:
|
|
86
|
+
|
|
87
|
+
```ts
|
|
88
|
+
export function dashboard(_req: Request, res: Response): void {
|
|
89
|
+
res.render('dashboard', { user: { name: 'Ada' } });
|
|
90
|
+
}
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
**3.** Mount the route in `src/routes/pages.ts`:
|
|
94
|
+
|
|
95
|
+
```ts
|
|
96
|
+
router.get('/dashboard', pages.dashboard);
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
**4.** Add semantic styles in `styles/styles.css`:
|
|
100
|
+
|
|
101
|
+
```css
|
|
102
|
+
.dashboard-page {
|
|
103
|
+
@apply px-6 py-4;
|
|
104
|
+
|
|
105
|
+
.page-title { @apply text-2xl font-bold; }
|
|
106
|
+
.page-subtitle { @apply text-sm text-gray-600 mt-2; }
|
|
107
|
+
}
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
**5.** Rebuild CSS and restart the dev server:
|
|
111
|
+
|
|
112
|
+
```bash
|
|
113
|
+
npm run tailwind:build
|
|
114
|
+
npm run dev
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Visit `/dashboard`.
|
|
118
|
+
|
|
119
|
+
### CSS convention
|
|
120
|
+
|
|
121
|
+
`cap-web` favours **semantic CSS classes** (e.g. `page-title`, `dashboard-page`) defined in `styles.css` with Tailwind's `@apply`, over presentational utility classes in the markup. Templates stay readable as the UI grows, and visual changes happen in one place. See `reference/web-ui.ref.md` for the full rationale.
|
|
122
|
+
|
|
123
|
+
## Added by
|
|
124
|
+
|
|
125
|
+
Included by default in the `web-app` profile.
|
|
126
|
+
|
|
127
|
+
Add to an existing project with:
|
|
128
|
+
|
|
129
|
+
```bash
|
|
130
|
+
boop add web
|
|
131
|
+
```
|