@symbo.ls/mcp 1.0.11 → 1.0.14
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 +1 -0
- package/package.json +1 -1
- package/symbols_mcp/skills/AUDIT.md +148 -174
- package/symbols_mcp/skills/BRAND_IDENTITY.md +75 -0
- package/symbols_mcp/skills/COMPONENTS.md +151 -306
- package/symbols_mcp/skills/COOKBOOK.md +850 -0
- package/symbols_mcp/skills/DEFAULT_COMPONENTS.md +3856 -0
- package/symbols_mcp/skills/DEFAULT_LIBRARY.md +301 -0
- package/symbols_mcp/skills/DESIGN_CRITIQUE.md +70 -59
- package/symbols_mcp/skills/DESIGN_DIRECTION.md +109 -175
- package/symbols_mcp/skills/DESIGN_SYSTEM.md +473 -181
- package/symbols_mcp/skills/DESIGN_SYSTEM_ARCHITECT.md +65 -57
- package/symbols_mcp/skills/DESIGN_TO_CODE.md +83 -64
- package/symbols_mcp/skills/DESIGN_TREND.md +62 -50
- package/symbols_mcp/skills/FIGMA_MATCHING.md +69 -58
- package/symbols_mcp/skills/LEARNINGS.md +374 -0
- package/symbols_mcp/skills/MARKETING_ASSETS.md +71 -59
- package/symbols_mcp/skills/MIGRATION.md +158 -117
- package/symbols_mcp/skills/PATTERNS.md +101 -74
- package/symbols_mcp/skills/PRESENTATION.md +78 -0
- package/symbols_mcp/skills/PROJECT_STRUCTURE.md +114 -116
- package/symbols_mcp/skills/RULES.md +179 -148
- package/symbols_mcp/skills/RUNNING_APPS.md +476 -0
- package/symbols_mcp/skills/SEO-METADATA.md +33 -18
- package/symbols_mcp/skills/SNIPPETS.md +598 -0
- package/symbols_mcp/skills/SSR-BRENDER.md +99 -0
- package/symbols_mcp/skills/SYNTAX.md +356 -298
- package/symbols_mcp/skills/BRAND_INDENTITY.md +0 -69
- package/symbols_mcp/skills/THE_PRESENTATION.md +0 -69
|
@@ -0,0 +1,476 @@
|
|
|
1
|
+
# Running Symbols Apps — 4 Modes
|
|
2
|
+
|
|
3
|
+
## Overview
|
|
4
|
+
|
|
5
|
+
| Mode | Package/Tool | Best For | Build Step |
|
|
6
|
+
|---|---|---|---|
|
|
7
|
+
| **Local Project** | `@symbo.ls/cli` | Production apps, team collaboration | Optional |
|
|
8
|
+
| **CDN** | `smbls` via ESM CDN | Prototypes, demos, learning | None |
|
|
9
|
+
| **JSON Runtime** | `@symbo.ls/frank` | Data-driven apps, platform sync | None |
|
|
10
|
+
| **Remote Server** | Mermaid | Managed hosting on `*.symbo.ls` | Server-side |
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## 1. Local Project (Full Development Setup)
|
|
15
|
+
|
|
16
|
+
Standard way to build Symbols apps. Uses `smbls` CLI with structured `symbols/` directory. No build step for development — components are plain objects resolved at runtime.
|
|
17
|
+
|
|
18
|
+
### When to Use
|
|
19
|
+
- Full applications with routing, state, design systems
|
|
20
|
+
- Team collaboration via `smbls sync` / `smbls collab`
|
|
21
|
+
- Production deployments (Cloudflare, Vercel, Netlify, GitHub Pages, Symbols Platform)
|
|
22
|
+
- SSR with Brender
|
|
23
|
+
|
|
24
|
+
### Setup
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
npm i -g @symbo.ls/cli
|
|
28
|
+
smbls create my-app
|
|
29
|
+
cd my-app
|
|
30
|
+
npm start
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Or link to the Symbols platform:
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
smbls project create my-app --create-new
|
|
37
|
+
cd my-app
|
|
38
|
+
npm start
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
### Project Structure
|
|
42
|
+
|
|
43
|
+
```
|
|
44
|
+
my-app/
|
|
45
|
+
├── symbols.json # Project config (key, dir, bundler, brender)
|
|
46
|
+
├── package.json
|
|
47
|
+
└── symbols/
|
|
48
|
+
├── index.js # Root entry: re-exports everything
|
|
49
|
+
├── state.js # export default { key: value, ... }
|
|
50
|
+
├── dependencies.js # export default { 'pkg': 'version' }
|
|
51
|
+
├── config.js # export default { useReset: true, ... }
|
|
52
|
+
├── components/
|
|
53
|
+
│ ├── index.js # export * from './Navbar.js'
|
|
54
|
+
│ └── Navbar.js # export const Navbar = { ... }
|
|
55
|
+
├── pages/
|
|
56
|
+
│ ├── index.js # import-based route map (only file with imports)
|
|
57
|
+
│ └── main.js # export const main = { extends: 'Page', ... }
|
|
58
|
+
├── functions/
|
|
59
|
+
│ ├── index.js # export * from './myFn.js'
|
|
60
|
+
│ └── myFn.js # export const myFn = function() {}
|
|
61
|
+
├── methods/
|
|
62
|
+
│ └── index.js
|
|
63
|
+
└── designSystem/
|
|
64
|
+
├── index.js # export default { color, theme, font, ... }
|
|
65
|
+
├── color.js
|
|
66
|
+
└── theme.js
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
### Key Rules
|
|
70
|
+
- **No imports between project files** (except `pages/index.js`)
|
|
71
|
+
- Components are plain objects, never functions
|
|
72
|
+
- Reference components by PascalCase key name in the tree
|
|
73
|
+
- `components/index.js` uses `export *` (never `export * as`)
|
|
74
|
+
|
|
75
|
+
### Deployment
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
smbls deploy --provider symbols # Symbols Platform (native)
|
|
79
|
+
smbls deploy --provider cloudflare # Cloudflare Pages
|
|
80
|
+
smbls deploy --provider vercel # Vercel
|
|
81
|
+
smbls deploy --provider netlify # Netlify
|
|
82
|
+
smbls deploy --provider github-pages # GitHub Pages
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
All providers run `smbls build` first, outputting to `dist/`.
|
|
86
|
+
|
|
87
|
+
### SSR with Brender
|
|
88
|
+
|
|
89
|
+
Enable in `symbols.json`:
|
|
90
|
+
|
|
91
|
+
```json
|
|
92
|
+
{ "brender": true, "brenderDistDir": "dist-brender" }
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
```bash
|
|
96
|
+
smbls brender # pre-render all static routes
|
|
97
|
+
smbls brender --watch # watch mode
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
Generates static HTML with `data-br` hydration keys. Client-side DOMQL reconnects to pre-rendered DOM for full interactivity.
|
|
101
|
+
|
|
102
|
+
### Sync & Collaboration
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
smbls push # upload local -> platform
|
|
106
|
+
smbls fetch --update # download platform -> local
|
|
107
|
+
smbls sync # two-way sync
|
|
108
|
+
smbls collab # real-time collaboration (watch mode)
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
---
|
|
112
|
+
|
|
113
|
+
## 2. CDN (Browser-Only, Zero Build)
|
|
114
|
+
|
|
115
|
+
Run Symbols directly in the browser with a single HTML file. No npm, no bundler, no CLI.
|
|
116
|
+
|
|
117
|
+
### When to Use
|
|
118
|
+
- Quick prototypes and demos
|
|
119
|
+
- Learning Symbols / DOMQL syntax
|
|
120
|
+
- Embedding Symbols in existing websites
|
|
121
|
+
- Single-file interactive examples
|
|
122
|
+
- Environments where npm/Node.js is unavailable
|
|
123
|
+
|
|
124
|
+
### Quick Start
|
|
125
|
+
|
|
126
|
+
```html
|
|
127
|
+
<!doctype html>
|
|
128
|
+
<html lang="en">
|
|
129
|
+
<head>
|
|
130
|
+
<meta charset="UTF-8" />
|
|
131
|
+
<meta name="viewport" content="width=device-width, initial-scale=1, minimum-scale=1" />
|
|
132
|
+
<title>My Symbols App</title>
|
|
133
|
+
</head>
|
|
134
|
+
<body>
|
|
135
|
+
<script type="module">
|
|
136
|
+
import { create } from 'https://esm.sh/smbls'
|
|
137
|
+
|
|
138
|
+
create({
|
|
139
|
+
flow: 'column',
|
|
140
|
+
padding: 'C',
|
|
141
|
+
text: 'Hello from Symbols!'
|
|
142
|
+
})
|
|
143
|
+
</script>
|
|
144
|
+
</body>
|
|
145
|
+
</html>
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
### CDN Providers
|
|
149
|
+
|
|
150
|
+
| Provider | ESM Import | Recommended |
|
|
151
|
+
|---|---|---|
|
|
152
|
+
| **esm.sh** | `import { create } from 'https://esm.sh/smbls'` | Yes (best) |
|
|
153
|
+
| **jsDelivr** | `import { create } from 'https://cdn.jsdelivr.net/npm/smbls/+esm'` | Yes |
|
|
154
|
+
| **Skypack** | `import { create } from 'https://cdn.skypack.dev/smbls'` | Yes |
|
|
155
|
+
| **unpkg** | `import { create } from 'https://unpkg.com/smbls?module'` | OK |
|
|
156
|
+
|
|
157
|
+
Pin a version: `https://esm.sh/smbls@3.6.8`
|
|
158
|
+
|
|
159
|
+
### IIFE (Classic Script Tag)
|
|
160
|
+
|
|
161
|
+
For non-module usage, the IIFE build exposes `window.Smbls`:
|
|
162
|
+
|
|
163
|
+
```html
|
|
164
|
+
<script src="https://cdn.jsdelivr.net/npm/smbls"></script>
|
|
165
|
+
<script>
|
|
166
|
+
Smbls.create({
|
|
167
|
+
flow: 'y',
|
|
168
|
+
text: 'Hello!'
|
|
169
|
+
})
|
|
170
|
+
</script>
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
### Full CDN App Pattern
|
|
174
|
+
|
|
175
|
+
```html
|
|
176
|
+
<script type="module">
|
|
177
|
+
import { create } from 'https://esm.sh/smbls'
|
|
178
|
+
|
|
179
|
+
// Define reusable components as variables
|
|
180
|
+
const Card = {
|
|
181
|
+
flow: 'column',
|
|
182
|
+
padding: 'B',
|
|
183
|
+
round: 'A',
|
|
184
|
+
background: 'white.95',
|
|
185
|
+
border: '1px solid gray.1',
|
|
186
|
+
|
|
187
|
+
Title: { tag: 'h3', fontSize: 'B', fontWeight: '600' },
|
|
188
|
+
Description: { tag: 'p', fontSize: 'A', color: 'gray+20' }
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
const App = {
|
|
192
|
+
flow: 'column',
|
|
193
|
+
gap: 'B',
|
|
194
|
+
padding: 'C',
|
|
195
|
+
|
|
196
|
+
state: { count: 0 },
|
|
197
|
+
|
|
198
|
+
Counter: {
|
|
199
|
+
gap: 'A',
|
|
200
|
+
Label: { text: ({ state }) => `Count: ${state.count}` },
|
|
201
|
+
Inc: {
|
|
202
|
+
extends: 'Button',
|
|
203
|
+
text: '+',
|
|
204
|
+
onClick: (e, el, s) => s.update({ count: s.count + 1 })
|
|
205
|
+
}
|
|
206
|
+
}
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
// Mount with optional config
|
|
210
|
+
create(App, {
|
|
211
|
+
designSystem: { color: { primary: '#0066cc' } },
|
|
212
|
+
components: { Card },
|
|
213
|
+
functions: { /* callable via el.call('fnName') */ },
|
|
214
|
+
state: { /* global state */ }
|
|
215
|
+
})
|
|
216
|
+
</script>
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
### Available Builds
|
|
220
|
+
|
|
221
|
+
The `smbls` package ships four formats:
|
|
222
|
+
|
|
223
|
+
| Format | Path | Usage |
|
|
224
|
+
|---|---|---|
|
|
225
|
+
| ESM | `dist/esm/index.js` | `import` with bundler (unbundled files) |
|
|
226
|
+
| CJS | `dist/cjs/index.js` | `require('smbls')` (Node) |
|
|
227
|
+
| Browser | `dist/browser/index.js` | Bundled ESM for direct browser/CDN use |
|
|
228
|
+
| IIFE | `dist/iife/index.js` | `<script>` tag → `window.Smbls` global |
|
|
229
|
+
|
|
230
|
+
### Available Exports
|
|
231
|
+
|
|
232
|
+
Everything exported from `smbls` is available via CDN:
|
|
233
|
+
|
|
234
|
+
```js
|
|
235
|
+
import { create, Flex, Button, Icon, Link } from 'https://esm.sh/smbls'
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
Includes: `create()`, all UIKit components (`Flex`, `Button`, `Input`, `Link`, `Icon`, etc.), design tokens, state management, events, CSS-in-props.
|
|
239
|
+
|
|
240
|
+
### CDN Limitations
|
|
241
|
+
|
|
242
|
+
- **No component registry** — cannot use `childExtends: 'MyComponent'` without `components/index.js`. Repeat shared styles inline or define JS variables.
|
|
243
|
+
- **No file-based routing** — no `pages/` folder, no `$router`. Use tab/view switching with DOM IDs.
|
|
244
|
+
- **No SSR** — client-side only.
|
|
245
|
+
- **Load time** — first load fetches dependencies from CDN (cached after).
|
|
246
|
+
|
|
247
|
+
### CDN vs Local Project
|
|
248
|
+
|
|
249
|
+
| Feature | Local Project | CDN |
|
|
250
|
+
|---|---|---|
|
|
251
|
+
| Component registry | `components/` folder | `components` option in `create()` |
|
|
252
|
+
| File-based routing | `pages/` folder | Not available (use tab switching) |
|
|
253
|
+
| `childExtends: 'Name'` | Works (registered components) | Works if passed in `components` |
|
|
254
|
+
| Design system | `designSystem/` folder | `designSystem` option in `create()` |
|
|
255
|
+
| SSR | Yes (Brender) | No (client-side only) |
|
|
256
|
+
| Build step | Optional (for production) | None |
|
|
257
|
+
|
|
258
|
+
---
|
|
259
|
+
|
|
260
|
+
## 3. JSON Runtime (`@symbo.ls/frank`)
|
|
261
|
+
|
|
262
|
+
Bidirectional transformation between Symbols project directories and JSON. Run Symbols apps from pure data — no filesystem, no imports.
|
|
263
|
+
|
|
264
|
+
### When to Use
|
|
265
|
+
- Storing/transporting Symbols apps as data (databases, APIs)
|
|
266
|
+
- Platform-to-local and local-to-platform synchronization
|
|
267
|
+
- Server-side rendering from stored project data
|
|
268
|
+
- Dynamic app loading without filesystem access
|
|
269
|
+
- Headless CMS or visual editor backends
|
|
270
|
+
|
|
271
|
+
### How It Works
|
|
272
|
+
|
|
273
|
+
**Project -> JSON** (`toJSON`):
|
|
274
|
+
```js
|
|
275
|
+
import { toJSON } from '@symbo.ls/frank'
|
|
276
|
+
|
|
277
|
+
const projectData = await toJSON({
|
|
278
|
+
entry: './symbols', // project directory
|
|
279
|
+
stringify: true, // serialize functions to strings
|
|
280
|
+
})
|
|
281
|
+
// Returns: { components, pages, designSystem, state, functions, methods, config, dependencies, ... }
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
**JSON -> Project** (`toFS`):
|
|
285
|
+
```js
|
|
286
|
+
import { toFS } from '@symbo.ls/frank'
|
|
287
|
+
|
|
288
|
+
await toFS(projectData, './output-dir', { overwrite: true })
|
|
289
|
+
// Generates full symbols/ directory structure from JSON
|
|
290
|
+
```
|
|
291
|
+
|
|
292
|
+
### JSON Output Structure
|
|
293
|
+
|
|
294
|
+
```json
|
|
295
|
+
{
|
|
296
|
+
"components": {
|
|
297
|
+
"Navbar": "{ flow: 'x', ... }",
|
|
298
|
+
"Card": "{ flow: 'y', ... }"
|
|
299
|
+
},
|
|
300
|
+
"pages": {
|
|
301
|
+
"/": "{ extends: 'Page', ... }",
|
|
302
|
+
"/about": "{ extends: 'Page', ... }"
|
|
303
|
+
},
|
|
304
|
+
"designSystem": {
|
|
305
|
+
"color": { "primary": "#0066cc" },
|
|
306
|
+
"theme": { "dialog": { "round": "A" } }
|
|
307
|
+
},
|
|
308
|
+
"state": { "user": {}, "activeModal": false },
|
|
309
|
+
"functions": { "switchView": "function switchView() { ... }" },
|
|
310
|
+
"methods": {},
|
|
311
|
+
"config": { "useReset": true, "useVariable": true },
|
|
312
|
+
"dependencies": { "chart.js": "4.4.9" },
|
|
313
|
+
"files": {}
|
|
314
|
+
}
|
|
315
|
+
```
|
|
316
|
+
|
|
317
|
+
### CLI Usage
|
|
318
|
+
|
|
319
|
+
```bash
|
|
320
|
+
# Project directory -> JSON file
|
|
321
|
+
smbls frank to-json ./symbols -o project.json
|
|
322
|
+
|
|
323
|
+
# JSON file -> project directory
|
|
324
|
+
smbls frank to-fs project.json -o ./output
|
|
325
|
+
```
|
|
326
|
+
|
|
327
|
+
### Integration with Mermaid Server
|
|
328
|
+
|
|
329
|
+
The Mermaid server (see section 4) loads apps from frank-generated JSON:
|
|
330
|
+
|
|
331
|
+
```bash
|
|
332
|
+
JSON_PATH=./project.json node mermaid/index.js
|
|
333
|
+
```
|
|
334
|
+
|
|
335
|
+
This is how the Symbols platform stores and serves projects — frank serializes for storage, mermaid deserializes for rendering.
|
|
336
|
+
|
|
337
|
+
---
|
|
338
|
+
|
|
339
|
+
## 4. Remote Symbols Server (Mermaid)
|
|
340
|
+
|
|
341
|
+
Rendering server that hosts Symbols apps on dynamic subdomains (`*.symbo.ls`, `*.preview.symbols.app`) and custom domains. Fetches project data and renders full HTML pages.
|
|
342
|
+
|
|
343
|
+
### When to Use
|
|
344
|
+
- Hosting apps on `*.symbo.ls` or `*.preview.symbols.app` subdomains
|
|
345
|
+
- Custom domain hosting for Symbols apps
|
|
346
|
+
- Managed deployment via `smbls push` / `smbls deploy`
|
|
347
|
+
- Multi-environment support (dev, staging, production)
|
|
348
|
+
- SEO-optimized server-rendered pages
|
|
349
|
+
|
|
350
|
+
### How It Works
|
|
351
|
+
|
|
352
|
+
1. Deploy via `smbls push` -> project data stored on Symbols platform
|
|
353
|
+
2. Request hits `myapp.nikoloza.preview.symbols.app`
|
|
354
|
+
3. Mermaid resolves appkey from subdomain
|
|
355
|
+
4. Fetches project data (from DB, gateway, or local JSON)
|
|
356
|
+
5. Generates JavaScript bundle from project data
|
|
357
|
+
6. In production: pre-renders HTML via Brender (SSR)
|
|
358
|
+
7. Returns complete HTML page with SEO metadata
|
|
359
|
+
|
|
360
|
+
### URL Patterns
|
|
361
|
+
|
|
362
|
+
```
|
|
363
|
+
# Production
|
|
364
|
+
https://myapp.nikoloza.preview.symbols.app/
|
|
365
|
+
|
|
366
|
+
# Development
|
|
367
|
+
https://myapp.nikoloza.preview.dev.symbols.app/
|
|
368
|
+
|
|
369
|
+
# Staging
|
|
370
|
+
https://myapp.nikoloza.preview.staging.symbols.app/
|
|
371
|
+
|
|
372
|
+
# Legacy format
|
|
373
|
+
https://myapp.symbo.ls/
|
|
374
|
+
|
|
375
|
+
# Custom domain
|
|
376
|
+
https://yourdomain.com/
|
|
377
|
+
```
|
|
378
|
+
|
|
379
|
+
### Deployment
|
|
380
|
+
|
|
381
|
+
```bash
|
|
382
|
+
# Push to Symbols platform
|
|
383
|
+
smbls push
|
|
384
|
+
|
|
385
|
+
# The app is live at:
|
|
386
|
+
# https://<project>.<username>.preview.symbols.app/
|
|
387
|
+
```
|
|
388
|
+
|
|
389
|
+
### Channels
|
|
390
|
+
|
|
391
|
+
| Channel | URL Pattern | SEO | Use Case |
|
|
392
|
+
|---|---|---|---|
|
|
393
|
+
| **production** | `*.preview.symbols.app` | Indexed | Live site |
|
|
394
|
+
| **staging** | `*.preview.staging.symbols.app` | noindex | QA/review |
|
|
395
|
+
| **development** | `*.preview.dev.symbols.app` | noindex | Active dev |
|
|
396
|
+
|
|
397
|
+
### Custom Domains
|
|
398
|
+
|
|
399
|
+
Attach custom domains through the Symbols platform. Mermaid resolves custom domains to the correct project data.
|
|
400
|
+
|
|
401
|
+
### Self-Hosting Mermaid
|
|
402
|
+
|
|
403
|
+
Run as:
|
|
404
|
+
|
|
405
|
+
1. **Node.js server**: `node mermaid/index.js` (port 3333)
|
|
406
|
+
2. **Cloudflare Worker**: `npx wrangler deploy` (edge deployment)
|
|
407
|
+
3. **With local JSON**: `JSON_PATH=./project.json node mermaid/index.js`
|
|
408
|
+
|
|
409
|
+
Environment variables:
|
|
410
|
+
|
|
411
|
+
| Variable | Purpose | Default |
|
|
412
|
+
|---|---|---|
|
|
413
|
+
| `PORT` | HTTP port | 3333 |
|
|
414
|
+
| `APPKEY` | Lock to specific project | (from Host header) |
|
|
415
|
+
| `MONGODB_URI` | Direct DB connection | — |
|
|
416
|
+
| `GATEWAY_URL` | Gateway endpoint | — |
|
|
417
|
+
| `JSON_PATH` | Local JSON file | — |
|
|
418
|
+
| `NODE_ENV` | development/staging/production | development |
|
|
419
|
+
|
|
420
|
+
### Data Flow
|
|
421
|
+
|
|
422
|
+
```
|
|
423
|
+
Local Project ──(frank toJSON)──> JSON Data ──(store)──> Database
|
|
424
|
+
│
|
|
425
|
+
Browser Request ──> Mermaid Server ──(fetch)────────────────┘
|
|
426
|
+
│
|
|
427
|
+
Render HTML ──> Response
|
|
428
|
+
```
|
|
429
|
+
|
|
430
|
+
---
|
|
431
|
+
|
|
432
|
+
## Comparison
|
|
433
|
+
|
|
434
|
+
| Feature | Local Project | CDN | JSON Runtime | Remote Server |
|
|
435
|
+
|---|---|---|---|---|
|
|
436
|
+
| Setup complexity | Medium | None | Low | Low (managed) |
|
|
437
|
+
| Build step | Optional | None | None | Server-side |
|
|
438
|
+
| Routing | Full (`pages/`) | Manual | Full | Full |
|
|
439
|
+
| Component registry | Yes | Limited | Yes | Yes |
|
|
440
|
+
| SSR | Yes (Brender) | No | Yes (via Mermaid) | Yes |
|
|
441
|
+
| State management | Full | Full | Full | Full |
|
|
442
|
+
| Design system | File-based | Inline | JSON | JSON |
|
|
443
|
+
| Collaboration | `smbls collab` | No | Platform | Platform |
|
|
444
|
+
| Custom domains | Via deploy | No | No | Yes |
|
|
445
|
+
| SEO | With Brender | No | With Mermaid | Yes |
|
|
446
|
+
| Offline | Yes | No (first load) | Yes | No |
|
|
447
|
+
| Best for | Production apps | Prototypes | Data-driven apps | Managed hosting |
|
|
448
|
+
|
|
449
|
+
---
|
|
450
|
+
|
|
451
|
+
## Detection Guide
|
|
452
|
+
|
|
453
|
+
### Local Project
|
|
454
|
+
- Has `symbols.json` in root
|
|
455
|
+
- Has `symbols/` directory with `components/`, `pages/`, etc.
|
|
456
|
+
- Has `package.json` with `smbls` dependency
|
|
457
|
+
- Uses `smbls start` / `smbls build` commands
|
|
458
|
+
|
|
459
|
+
### CDN
|
|
460
|
+
- Single `index.html` file (or few HTML files)
|
|
461
|
+
- Contains `import ... from 'https://esm.sh/smbls'` or similar CDN URL
|
|
462
|
+
- Or uses `<script src="https://cdn.jsdelivr.net/npm/smbls"></script>` (IIFE)
|
|
463
|
+
- No `package.json` or `symbols.json`
|
|
464
|
+
- No `symbols/` directory
|
|
465
|
+
|
|
466
|
+
### JSON Runtime
|
|
467
|
+
- Has `.json` files containing serialized Symbols project data
|
|
468
|
+
- Uses `@symbo.ls/frank` for conversion
|
|
469
|
+
- May have `JSON_PATH` environment variable
|
|
470
|
+
- Project data stored in database or API
|
|
471
|
+
|
|
472
|
+
### Remote Server
|
|
473
|
+
- Deployed to `*.symbo.ls` or `*.preview.symbols.app`
|
|
474
|
+
- Uses `smbls push` for deployment
|
|
475
|
+
- May have custom domain configured
|
|
476
|
+
- Mermaid server handles rendering
|
|
@@ -1,19 +1,32 @@
|
|
|
1
1
|
# SEO Metadata
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
3
|
+
Define a declarative `metadata` object on any app, page, or component. Works at runtime (updates DOM `<head>`) and during SSR (generates HTML via brender). Provided by `@symbo.ls/helmet`.
|
|
4
|
+
|
|
5
|
+
## Supported Metadata Types
|
|
6
|
+
|
|
7
|
+
| Prefix / Type | Generates | Example Key |
|
|
8
|
+
|---|---|---|
|
|
9
|
+
| _(none)_ | `<title>`, `<meta name>`, `<link rel>` | `title`, `description`, `canonical` |
|
|
10
|
+
| `og:` | `<meta property="og:...">` | `og:title`, `og:image` |
|
|
11
|
+
| `twitter:` | `<meta name="twitter:...">` | `twitter:card`, `twitter:site` |
|
|
12
|
+
| `article:` | `<meta property="article:...">` | `article:published_time` |
|
|
13
|
+
| `product:` | `<meta property="product:...">` | `product:price:amount` |
|
|
14
|
+
| `DC:` | `<meta name="DC....">` | `DC:title`, `DC:creator` |
|
|
15
|
+
| `itemprop:` | `<meta itemprop="...">` | `itemprop:name` |
|
|
16
|
+
| `http-equiv:` | `<meta http-equiv="...">` | `http-equiv:cache-control` |
|
|
17
|
+
| `apple:` | `<meta name="apple:...">` | `apple:mobile-web-app-capable` |
|
|
18
|
+
| `msapplication:` | `<meta name="msapplication:...">` | `msapplication:TileColor` |
|
|
19
|
+
| `alternate` | `<link rel="alternate" ...>` | `alternate: [{ hreflang, href }]` |
|
|
20
|
+
| `customMeta` | `<meta ...attrs>` | `customMeta: { name, content }` |
|
|
21
|
+
|
|
22
|
+
**Behaviors:**
|
|
23
|
+
- Array values expand into multiple tags
|
|
24
|
+
- Function values receive `(element, state)` for dynamic metadata
|
|
25
|
+
- Merges metadata from global, app-level, and page-level (page wins)
|
|
13
26
|
|
|
14
27
|
---
|
|
15
28
|
|
|
16
|
-
|
|
29
|
+
## Complete Example
|
|
17
30
|
|
|
18
31
|
```js
|
|
19
32
|
export default {
|
|
@@ -113,7 +126,7 @@ export default {
|
|
|
113
126
|
|
|
114
127
|
---
|
|
115
128
|
|
|
116
|
-
|
|
129
|
+
## Dynamic Metadata
|
|
117
130
|
|
|
118
131
|
Metadata values can be functions receiving `(element, state)`. Both the whole object and individual properties support this:
|
|
119
132
|
|
|
@@ -139,12 +152,14 @@ export const profilePage = {
|
|
|
139
152
|
|
|
140
153
|
---
|
|
141
154
|
|
|
142
|
-
|
|
155
|
+
## Merge Priority
|
|
143
156
|
|
|
144
|
-
|
|
157
|
+
Higher priority wins. Later levels override earlier ones.
|
|
145
158
|
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
159
|
+
| Priority | Source | Scope |
|
|
160
|
+
|---|---|---|
|
|
161
|
+
| 1 (lowest) | `data.integrations.seo` | Global SEO settings |
|
|
162
|
+
| 2 | `data.app.metadata` | App-level defaults |
|
|
163
|
+
| 3 (highest) | `page.metadata` | Page-level overrides |
|
|
149
164
|
|
|
150
|
-
|
|
165
|
+
**Fallback chain for `title`:** `page.metadata.title` -> `page.state.title` -> `data.name`
|