@teambit/host-initializer 0.0.870 → 0.0.871

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.
Files changed (6) hide show
  1. package/agents-template-git.md +239 -44
  2. package/agents-template.md +316 -81
  3. package/dist/agents-template-git.md +239 -44
  4. package/dist/agents-template.md +316 -81
  5. package/package.json +3 -3
  6. /package/dist/{preview-1788878075084.js → preview-1788904049748.js} +0 -0
package/dist/agents-template.md CHANGED
@@ -16,8 +16,8 @@ Not all components are UI widgets. In Bit, a "component" can be any of these:
16
16
  | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
17
17
  | **Entity** | Plain domain object — defines the shape and behavior of a domain model. No React, no side effects. | `entities/user`, `entities/order` |
18
18
  | **Hook** | Encapsulates data fetching, mutations, or stateful logic for a domain. Consumed by UI components and pages. | `hooks/use-user`, `hooks/use-orders` |
19
- | **UI component** | Reusable visual element, typically stateless or lightly stateful. | `ui/button`, `ui/card` |
20
- | **Feature / Aspect** | Self-contained domain slice — owns its entities, hooks, pages, and backend logic. | `customers`, `billing` |
19
+ | **UI component** | Reusable visual element, typically stateless or lightly stateful | `ui/button`, `ui/card` |
20
+ | **Feature / Aspect** | Self-contained domain slice — owns its entities, hooks, pages, and backend logic | `customers`, `billing` |
21
21
  | **App** | A standard deployable application — a React frontend, Node.js server, etc. | `my-react-app`, `my-node-server` |
22
22
  | **Platform** | The app-level composition that wires aspects together into a running system. Often named `*-platform`. Not a framework concept — just the component responsible for composing aspects into the app. | `my-platform` |
23
23
  | **Platform aspect** | A special aspect that exposes the registration API other aspects use to plug in (routes, backend servers, etc.). Lives as its own aspect component, typically named `platform-aspect`. | `platform-aspect` |
@@ -25,37 +25,23 @@ Not all components are UI widgets. In Bit, a "component" can be any of these:
25
25
  Understanding which type you're working with matters because it shapes the dependency chain. A typical full chain of a platform looks like:
26
26
 
27
27
  ```
28
- Platform → Feature/Aspect → Page → Hook → Entity
29
- ↘ UI component
28
+ Platform → Feature/Aspect → Page → Hook → Entity
29
+ ↘ UI component
30
30
  ```
31
31
 
32
- For an app, the blueprint looks like:
32
+ Where the blueprint of an app, look like this:
33
33
 
34
34
  ```
35
- App → Page → Hook (optional) → Entity (optional)
35
+ App → Page → Hook (optional) → Entity (optional)
36
36
  ↘ UI component
37
37
  ```
38
38
 
39
- Entities and hooks sit at the bottom of the chain — they have no dependents of their own, so changes to them propagate upward. Everything above that consumes them must be local for your changes to take effect.
39
+ Entities and hooks sit at the bottom of the chain — they have no dependents of their own, so changes to them propagate upward. You don't need to import anything below them, but everything above that consumes them must be local for your changes to take effect.
40
40
 
41
41
  The workspace is defined by `workspace.jsonc`. The owner and default scope are set there — always read them first.
42
42
 
43
43
  ---
44
44
 
45
- ## Bit Cloud MCP
46
-
47
- This workspace ships with a `.mcp.json` that wires up the **Bit Cloud MCP** server (`https://mcp.bit.cloud/mcp`). When the MCP is connected and authenticated (the agent will prompt for OAuth on first use), it is the fastest way to discover and inspect components that live in remote scopes — prefer it over reading source files or installing packages just to look around.
48
-
49
- Key tools to reach for:
50
-
51
- - **`read_scopes`** — list scopes and their components for a given `owner` (read from `workspace.jsonc`). Prefer this over broad `search` for discovery.
52
- - **`read_components`** — structured type signatures, dependencies, and metadata for one or more remote components, in a single call. API references are included by default.
53
- - **`search`** — keyword search across remote scopes.
54
-
55
- When in doubt, ask the MCP before scaffolding anything new. If the MCP is not connected, fall back to the local `bit` CLI commands (`bit list`, `bit show`, `bit schema`).
56
-
57
- ---
58
-
59
45
  ## Project Orientation
60
46
 
61
47
  ```bash
@@ -65,18 +51,48 @@ bit status # check for pending changes
65
51
  bit templates # see what generators are available
66
52
  ```
67
53
 
68
- When using the Bit Cloud MCP, always pass the `owner` from `workspace.jsonc`. Prefer `read_scopes` over `search` for broader discovery.
54
+ ---
55
+
56
+ ## Scopes & the Bit Cloud MCP
57
+
58
+ A **scope** is a remote registry for one business domain — and the unit a full-stack feature ships as (see _Full-Stack Apps_). A component ID is `<owner>.<scope>/<name>`, optionally with a namespace before the name: `<owner>.<scope>/<namespace>/<name>`. The namespace is optional — don't add one to an ID that doesn't have it.
59
+
60
+ Anything remote — scopes, components, lanes, change requests — goes through the **Bit Cloud MCP**, not the CLI. The server advertises its own tools; two rules about _ordering_ them:
61
+
62
+ - Start with `orientation` when you don't know the account's topology, then `read_scope` to go deep on one domain. Reach for `search_components` only when you don't know which scope owns something.
63
+ - Always pass the `owner` from `workspace.jsonc`.
64
+
65
+ **If the MCP isn't connected, don't stop** — the CLI can read remotes too, just less efficiently. `bit list <owner>.<scope>` lists a remote scope's components, `bit show <owner>.<scope>/<name> --remote` inspects one, and `bit search <query>` searches by keyword across both the local workspace and Bit Cloud. Say that the MCP is unavailable and carry on; only scope creation has no CLI fallback.
66
+
67
+ ### Creating a scope
68
+
69
+ **Don't create a scope up front — create it before you export.** `bit create <template> <name> --scope <owner>.<scope>` only records the scope ID locally, so you can build, validate and iterate against a scope that doesn't exist on Bit Cloud yet. The scope only has to exist by the time you publish, and creating one you never export to just leaves an empty scope on the account.
70
+
71
+ The gate is right before `bit export`: for every scope you're about to publish to, confirm it exists (`read_scope` → `existsOnCloud`) and create the missing ones first. An export to a scope that doesn't exist fails. `bit snap` and `bit tag` only write to the local scope, so they don't need it.
72
+
73
+ Scopes cannot be created from the CLI — use the `create_scope` MCP tool, or https://bit.cloud/create-scope in the browser.
74
+
75
+ **Look before you create.** Run `orientation` first — if the work fits a domain that already exists, put the components there. Create a scope only when the domain is genuinely new.
76
+
77
+ ```
78
+ create_scope({ owner: 'acme', scopeName: 'billing', displayName: 'Billing', description: 'Invoicing and subscriptions' })
79
+ ```
80
+
81
+ - `scopeName` — lowercase letters, digits and dashes, starting with a letter (2 chars minimum). The resulting ID is `<owner>.<scopeName>`.
82
+ - `owner` — defaults to the current account. You must be the account owner or an admin of that organization, otherwise the call is denied.
83
+ - `visibility` — optional, `public` or `private`. Defaults to public on the free plan and private on paid plans.
84
+ - `confirmed` — on paid plans the first call returns a **preview instead of creating**. Show it to the user, get approval, then call again with `confirmed: true`. On the free plan the scope is created on the first call.
69
85
 
70
86
  ---
71
87
 
72
88
  ## Understanding Component APIs
73
89
 
74
- When you need to understand how to **use** a component (its props, function signatures, return types), prefer structured API data over reading source files:
90
+ When you need to understand how to **use** a component (its props, function signatures, return types), use structured API data instead of reading source files:
75
91
 
76
- - **Remote components:** use `read_components` (Bit Cloud MCP) — returns structured type signatures, dependencies, and metadata in a single call. API references are included by default. As a CLI fallback, run `bit show <owner>.<scope>/<name>`.
77
- - **Local workspace components:** run `bit schema <component-id>` — returns exported types, function signatures, and class methods.
92
+ - **Remote components**: Use `read_components` (Bit Cloud MCP) — returns structured type signatures, dependencies, and metadata in a single call. API references are included by default.
93
+ - **Local workspace components**: Run `bit schema <component-id>` — displays exported types, function signatures, and class methods.
78
94
 
79
- For understanding implementation details (how something works internally), read the source directly.
95
+ These structured APIs are significantly more compact than reading source files. For understanding implementation details (how something works internally), use `read-file` or read the source directly.
80
96
 
81
97
  ---
82
98
 
@@ -86,30 +102,31 @@ For understanding implementation details (how something works internally), read
86
102
  bit status # workspace health + pending changes
87
103
  bit start # dev server (default port 3000)
88
104
  bit run [app_name] # run the app
89
- bit list # all locally tracked components (do not pass args)
90
- bit search <query> # search components locally and on remote scopes (CLI fallback — prefer MCP for remote)
105
+ bit list # all locally tracked components (do not pass args to the command)
91
106
  bit show <owner>.<scope>/<name> # inspect a specific component
92
- bit schema <component-id> # structured API of a local component
93
107
  bit import "<owner>.<scope>/**" # import all components from a remote scope
94
108
  bit templates # list available generator templates
95
109
  bit create <template> <name> # scaffold a new component
96
110
  bit install [pkg1] [pkg2] ... # install package dependencies
97
- bit compile # manual compile (usually auto — use for troubleshooting)
98
- bit validate # lint + type-check + tests (fast build) — preferred check
111
+ bit compile # rebuild dist/ — automatic while bit watch/start runs, manual otherwise
112
+ bit validate # lint + type-check + tests (fast build)
99
113
  bit test # run tests only
100
114
  bit lint # run linter only
101
- bit check-types # TypeScript type checker only
102
- bit ripple <sub-command> # manage Ripple CI jobs on bit.cloud — list/log/errors/retry/stop (jobs that build components in the cloud after export)
115
+ bit check-types --strict # TypeScript type checker only (without --strict it exits 0 even on errors)
116
+ bit ripple log # check Ripple CI build status (auto-detects current lane)
117
+ bit ripple errors # show build errors for a Ripple CI job
118
+ bit ripple retry # retry a failed Ripple CI job
119
+ bit ripple stop # stop a running Ripple CI job
103
120
  ```
104
121
 
105
122
  > **Never run `bit build`** unless absolutely necessary. Always use `bit validate` instead — it's faster and sufficient.
106
123
  >
107
- > **Always use `bit install`** to install packages. Never use `npm install`, `yarn`, or `pnpm` directly — unless the workspace is configured with `externalPackageManager` mode in `workspace.jsonc`, in which case use your configured package manager.
124
+ > **Always use `bit install`** to install packages. Never use `npm install`, `yarn`, or `pnpm` directly.
108
125
  >
109
126
  > **Use Bit for type checking and testing.** Never use `tsc` or `npx tsc` directly. Use `bit validate` for a full check, or scope to specific components:
110
127
  >
111
128
  > ```bash
112
- > bit check-types "[component-id1, component-id2]"
129
+ > bit check-types --strict "[component-id1, component-id2]"
113
130
  > bit test "[component-id1, component-id2]"
114
131
  > bit validate "[component-id1, component-id2]"
115
132
  > ```
@@ -118,13 +135,13 @@ bit ripple <sub-command> # manage Ripple CI jobs on bit.cloud — li
118
135
 
119
136
  ## Discovering Apps
120
137
 
121
- ```bash
138
+ To list apps in the workspace run the following command:
139
+
140
+ ```
122
141
  bit app list
123
142
  ```
124
143
 
125
- Use the Bit Cloud MCP to list remote apps in a given scope. Use `bit import` to fetch remote apps and run them locally.
126
-
127
- ---
144
+ Use the Bit Cloud MCP to list remote apps. Use `bit import` to fetch remote apps and run them locally.
128
145
 
129
146
  ## The Golden Rule: One Component at a Time
130
147
 
@@ -134,20 +151,20 @@ Never scaffold multiple components upfront. Bit development is an **iterative lo
134
151
  render → identify gap → create ONE component → render again
135
152
  ```
136
153
 
137
- ### Step-by-step
154
+ ### Step-by-step Process
138
155
 
139
- 1. **Look before you create.** Search the workspace and the Bit Cloud MCP first:
156
+ 1. **Look before you create.** Search the workspace and Bit Cloud MCP first:
140
157
 
141
158
  ```bash
142
- bit list # what's already local
143
- bit show <owner>.<scope>/<name> # inspect a candidate
159
+ bit list
160
+ bit show <owner>.<scope>/<name>
144
161
  ```
145
162
 
146
- And via the MCP: `read_scopes` for the workspace `owner` to see existing components, or `search` for keyword discovery. A component may already exist locally or remotely. Don't duplicate.
163
+ A component may already exist locally or remotely. Don't duplicate.
147
164
 
148
- 2. **Identify the entry point.** Depending on what you're building, the entry point could be a platform, app, or feature/aspect. Use the MCP (`read_scopes` / `read_components`) to list what exists in the scope before creating anything new.
165
+ 2. **Identify the entry point.** Depending on what you're building, the entry point could be a platform, app, or feature/aspect. Use the MCP to list what exists in the scope before creating anything new.
149
166
 
150
- 3. **Create one component.** Scaffold it, wire it in, verify it compiles and renders.
167
+ 3. **Create one component.** Scaffold it, wire it into the app, and verify it compiles and renders.
151
168
 
152
169
  4. **Validate before moving on:**
153
170
 
@@ -159,15 +176,15 @@ render → identify gap → create ONE component → render again
159
176
 
160
177
  6. **Repeat.** Never pre-plan a list of components and create them all at once.
161
178
 
162
- #### Example
179
+ #### Example Commands
163
180
 
164
- Create a UI component:
181
+ Create UI component:
165
182
 
166
183
  ```bash
167
184
  bit create react pages/login --scope acme.people
168
185
  ```
169
186
 
170
- Create a data entity:
187
+ Create data entity:
171
188
 
172
189
  ```bash
173
190
  bit create entity entities/user --scope acme.people
@@ -181,19 +198,19 @@ Bit resolves **local workspace components** over their installed package version
181
198
 
182
199
  ### The full dependency chain must be local
183
200
 
184
- When modifying any component, import every component in the chain from the top down to your target:
201
+ When modifying any component, import every component in the chain from the top down to your target. The chain depends on what type of component you're working with:
185
202
 
186
203
  ```
187
204
  Platform → App → Feature/Aspect → Page → UI component
188
205
  ```
189
206
 
190
- You don't always need the full chain — only the layers in the dependency path of your change. But every layer between the entry point and your target must be local. If any layer in between is still installed as a package (not local), the app will ignore your changes to the layers below it.
207
+ You don't always need the full chain — only the layers that are in the dependency path of your change. But every layer between the entry point and your target must be local. If any layer in between is still installed as a package (not local), the app will ignore your changes to the layers below it.
191
208
 
192
209
  **Examples:**
193
210
 
194
- - Changing a UI component used by a feature page → import the feature, the page, and the UI component.
195
- - Changing a feature's backend logic → import the platform, the app, and the feature/aspect.
196
- - Changing the platform itself → import the platform only (everything downstream will pick it up once local).
211
+ - Changing a UI component used by a feature page → import the feature, the page, and the UI component
212
+ - Changing a feature's backend logic → import the platform, the app, and the feature/aspect
213
+ - Changing the platform itself → import the platform only (everything downstream will pick it up once local)
197
214
 
198
215
  ### Finding the component ID
199
216
 
@@ -204,7 +221,7 @@ cat node_modules/@<org>/<package-name>/package.json | grep -A3 '"componentId"'
204
221
  # → component ID: myorg.myfeature/pages/my-page
205
222
  ```
206
223
 
207
- ### Importing
224
+ ### Importing Bit Components
208
225
 
209
226
  ```bash
210
227
  bit import <scope>/<name>
@@ -214,30 +231,86 @@ bit import myorg.myfeature/pages/my-page myorg.myfeature/pages/lobby-page
214
231
 
215
232
  Imported components land at `<scope-short-name>/<name>/` in the workspace.
216
233
 
217
- #### Importing whole scopes
234
+ #### Importing Entire Scopes
218
235
 
219
236
  ```bash
220
237
  bit import "<owner>.<scope>/**"
238
+ # e.g.
239
+ bit import "myorg.myfeature/**"
221
240
  ```
222
241
 
223
- ---
224
-
225
242
  ## Saving and Publishing Changes
226
243
 
227
244
  **Never push directly to the main lane.** Always create a lane and submit a change request.
228
245
 
229
- Git does not manage component versions in a Bit workspace — use Bit for version control of components.
246
+ Git does not exist in the workspace. Use only Bit for version control.
247
+
248
+ A **lane** collects and proposes component changes, in a similar fashion to a branch in Git. It can contain new components, changed components, and deletions. A lane is identified as `<scope>/<lane-name>` — for example `acme.billing/fix-invoice`. Never put a slash inside the lane name itself.
230
249
 
231
250
  ```bash
232
- bit lane create <your-lane-name> # create a new lane
251
+ bit lane current # which lane am I on? check before anything else
252
+ bit lane create <your-lane-name> # create a lane and switch to it
233
253
  bit validate # confirm no build errors first
234
254
  bit snap --message "describe change" # persist component versions
235
255
  bit export # push lane to remote
236
256
  ```
237
257
 
238
- > Always run `bit lane create` first. If you're already on a non-main lane, continue using it — don't create a new one.
258
+ > Always check `bit lane current` first. If you're already on a non-main lane, continue using it — don't create a new one.
239
259
 
240
- After exporting, components are built in the cloud by Ripple CI. Use `bit ripple log` to follow the current lane's job and `bit ripple errors` to inspect any build failures (or `bit ripple retry` to re-run it).
260
+ > **Before exporting**, make sure every scope you're publishing to exists on Bit Cloud — check `existsOnCloud` via `read_scope` and create the missing ones with `create_scope` (see _Creating a scope_). This is the point at which a scope must exist; don't create it earlier.
261
+
262
+ ### `bit snap` vs `bit tag`
263
+
264
+ Where you are decides which one you run — it is not a preference:
265
+
266
+ - **On a lane → `bit snap`.** Produces a hash, no version number. This is the default path.
267
+ - **On main → `bit tag`.** Produces a semver version. Bumps the patch by default; use `--minor` / `--major` only when the user describes a minor, major, or breaking release.
268
+
269
+ Both only write to the local scope. **`bit export` is what publishes** — until it runs, nothing has reached the remote scope or the deployment pipeline. Releasing to production from main is therefore tag _then_ export:
270
+
271
+ ```bash
272
+ bit validate # hard gate
273
+ bit tag --message "describe release"
274
+ bit export
275
+ bit ripple log # post the build link straight away
276
+ ```
277
+
278
+ `bit tag` is **only possible on main** — it is not a thing you can do on a lane, so there is no choice to make once `bit lane current` tells you where you are. On a lane, snap. And even on main, tagging is rejected when the scope protects `main` or the account requires review; then the lane workflow is the only path (see _When main is protected_).
279
+
280
+ Run `bit validate` before either — it's a hard gate, never snap or tag on a failing validate. And talk to the user in outcomes, not CLI verbs: "deploy to production" and "deploy to a preview lane", not "tag" and "snap".
281
+
282
+ ### Change requests
283
+
284
+ After exporting, open a change request so the lane can be reviewed and released:
285
+
286
+ - `submit_change_request` (Bit Cloud MCP) — open the change request for your lane
287
+ - `list_change_requests` — check its status
288
+ - `edit_change_request` — update its title or description
289
+
290
+ Ripple CI builds every export. Run `bit ripple log` as soon as the export returns, give the user the job link straight away (see _Deploying_), and check the build is green before asking anyone to review:
291
+
292
+ ```bash
293
+ bit ripple log # build status for the current lane
294
+ bit ripple errors # build errors for a failing job
295
+ bit ripple retry # retry a failed job
296
+ ```
297
+
298
+ ### After the lane is released
299
+
300
+ When the change request is **released** (merged to main), the lane is finished — but your workspace is still sitting on it. Switch back before starting anything new:
301
+
302
+ ```bash
303
+ bit lane current # confirm which lane you're on
304
+ bit switch main # move the workspace to main and fetch the released versions
305
+ bit status # verify a clean workspace on main
306
+ bit lane remove <your-lane-name> # optional: drop the now-merged local lane
307
+ ```
308
+
309
+ Never keep snapping onto a released lane — those snaps land somewhere nobody will review again. Start the next piece of work with a fresh `bit lane create`.
310
+
311
+ ### When main is protected
312
+
313
+ Scopes can protect `main`, and some accounts don't allow agents to release to it. If `bit export` or `bit tag` is rejected for that reason, do not retry and do not try to work around it — create a lane, snap, export, and open a change request instead.
241
314
 
242
315
  ---
243
316
 
@@ -249,13 +322,15 @@ Each component directory follows this convention:
249
322
  | ------------------------ | ------------------------------------ |
250
323
  | `<name>.tsx` | Main implementation |
251
324
  | `index.ts` | Public barrel export |
252
- | `<name>.spec.tsx` | Tests |
325
+ | `<name>.spec.tsx` | Vitest tests |
253
326
  | `<name>.composition.tsx` | Live previews (shown in `bit start`) |
254
327
  | `<name>.docs.mdx` | Documentation |
255
328
  | `<name>.mock.ts` | Mock data / fixtures |
256
329
  | `*-type.ts` | Standalone type definitions |
257
330
 
258
- > Add JSDocs to exported APIs, include two to three usage examples in the `.docs.mdx`, and two to three compositions for the live preview.
331
+ > Ensure proper JSDocs documentation, complete MDX docs with two to three usage examples. Add two to three composition for the component live preview.
332
+
333
+ JSDoc on exported members isn't optional polish — it's what renders as the component's API reference on Bit Cloud, and it's the first thing another agent reads when deciding whether to reuse the component. For the same reason, avoid `any` in a public signature: it erases the API for every consumer, and `bit check-types` gates publishing.
259
334
 
260
335
  ---
261
336
 
@@ -273,7 +348,7 @@ Never use relative paths across component boundaries. Always use the package not
273
348
 
274
349
  ## Environment Setup
275
350
 
276
- Generator environments (React, Vue, Node, Angular, etc.) are configured in `workspace.jsonc`. Some may be commented out. Enable the relevant environment before creating components for a specific framework.
351
+ Generator environments (React, Vue, Node, etc.) are configured in `workspace.jsonc`. Some may be commented out. Enable the relevant environment before creating components for a specific framework.
277
352
 
278
353
  ---
279
354
 
@@ -287,9 +362,104 @@ Generator environments (React, Vue, Node, Angular, etc.) are configured in `work
287
362
 
288
363
  ---
289
364
 
290
- ## Runtime Code Crossing Environment Boundaries
365
+ ## Full-Stack Apps
366
+
367
+ There are two ways to compose an app. Decide before creating anything:
368
+
369
+ - **Do NOT default to Harmony/Symphony — most projects do not need it.** For personal sites, MVPs, small-to-medium apps and single-team projects, use the simple `platform` composition below.
370
+ - Use **Harmony** only for large enterprise platforms with multiple teams that need extensibility, plugin architecture and IoC — or when the user explicitly asks for it.
371
+ - To tell what an existing workspace uses: check `workspace.jsonc` for `bitdev.symphony/symphony-platform`, or the code for `symphonyPlatform`. If neither is present, use simple platform composition.
372
+ - When it's unclear which fits, ask: _"Are you building a simple app/site, or an enterprise platform that multiple teams will extend?"_
373
+
374
+ ### Simple platform composition
375
+
376
+ Never hand-write boilerplate — scaffold with `bit create <template> <name>`, and run `bit templates` first to see what this workspace offers. If a template you need is missing, enable its env in `workspace.jsonc` generators.
377
+
378
+ A full-stack app is **three components composed by a platform**:
379
+
380
+ 1. `bit create platform <name>-platform` — the deployable unit
381
+ 2. `bit create react-app <name>-app` — the frontend
382
+ 3. `bit create express-server <name>-service` — the backend (name it after its domain; use the `-service` suffix, never `-api` or `-backend`)
291
383
 
292
- Importing frontend modules into Node.js runtime files or Node.js modules into browser runtime files causes app initialization failures. This typically happens when `index.ts` or runtime files import/export cross-environment modules by value instead of by type.
384
+ Then compose the app and the service in the platform and run `bit run <name>-platform`. The platform assigns ports and proxies, so the frontend never needs to know the backend port.
385
+
386
+ **Reaching the backend from the frontend.** The platform exposes the backend base URL to the React app as the `BACKEND_URL` environment variable — read it with `process.env.BACKEND_URL`:
387
+
388
+ ```ts
389
+ fetch(`${process.env.BACKEND_URL}/api/users`, { credentials: 'include' });
390
+ ```
391
+
392
+ Every cross-origin call to `BACKEND_URL` **must** pass `credentials: 'include'` — `credentials: 'include'` in `fetch`, or in the Apollo `HttpLink`. The platform gateway is configured for credentialed CORS (origin reflection plus `Access-Control-Allow-Credentials: true`), and without it the browser blocks the response. Do NOT add a Vite proxy or switch to relative paths as a workaround — the gateway already handles CORS correctly once credentials are included. This works the same way in Bit Cloud workspaces and in production.
393
+
394
+ MongoDB is already provisioned at `process.env.MONGO_URL`; never add an in-memory store or ask the user to set up a database.
395
+
396
+ Other common templates: `react`, `react-hook`, `react-theme` (UI); `module`, `entity`, `graphql-server` (Node).
397
+
398
+ ---
399
+
400
+ ## Harmony Platforms
401
+
402
+ **This section applies ONLY when the workspace uses Harmony/Symphony — if it doesn't, ignore everything here and use the simple platform composition above.**
403
+
404
+ Templates: `harmony-platform` (the platform), `aspect` (a domain that plugs into it), `platform-aspect` (the platform's entry aspect), `bit-aspect` (extend Bit itself).
405
+
406
+ An aspect is one domain's full vertical — its `*.node.runtime.ts` holds GraphQL, database and routes, its `*.browser.runtime.tsx` holds pages and routing, and neither may import the other's modules. Features register themselves into the platform; the platform never imports a feature.
407
+
408
+ ### Backend Registration
409
+
410
+ All GraphQL schemas and REST routes must be registered through `symphonyPlatform.registerBackendServer`. This is the only correct way — never use `registerMiddlewares` for endpoint logic.
411
+
412
+ ```ts
413
+ symphonyPlatform.registerBackendServer([
414
+ {
415
+ name: 'ai', // sets the gateway prefix: /ai/...
416
+ gql: gqlSchema, // optional — omit if no GraphQL
417
+ routes: [
418
+ {
419
+ path: '/stream',
420
+ method: 'post',
421
+ route: async (req, res) => { ... },
422
+ },
423
+ ],
424
+ },
425
+ ]);
426
+ ```
427
+
428
+ ### UI Layout Registration
429
+
430
+ `symphonyPlatform.registerLayoutEntry` registers a component **globally** — it renders on every page. Use it only for truly global sticky chrome like the top navigation header.
431
+
432
+ **Never use it for footers or any element that should appear on specific pages only.** Instead, import the component and render it directly inside the relevant page component(s).
433
+
434
+ ```tsx
435
+ // Wrong — makes footer appear on every page, sticky
436
+ symphonyPlatform.registerLayoutEntry([{ position: 'bottom', component: () => <Footer /> }]);
437
+
438
+ // Correct — add Footer directly inside the page
439
+ export function Homepage() {
440
+ return (
441
+ <div>
442
+ {/* page content */}
443
+ <Footer />
444
+ </div>
445
+ );
446
+ }
447
+ ```
448
+
449
+ ### Gateway Routing
450
+
451
+ The Symphony gateway proxies frontend calls to the backend, stripping the aspect name prefix:
452
+
453
+ ```
454
+ Frontend: /api/{name}/{path}
455
+ Backend receives: /{path}
456
+ ```
457
+
458
+ For example, `POST /api/ai/stream` → backend receives `POST /stream`. The frontend **must always** include the `/api` prefix.
459
+
460
+ ### Troubleshooting: Runtime Code Crossing Environment Boundaries
461
+
462
+ Importing frontend modules into Node.js or Node.js modules into the browser causes app initialization failures. This happens when `index.ts` or runtime files import/export cross-environment modules by value instead of by type.
293
463
 
294
464
  **Rules for aspect `index.ts` files:**
295
465
 
@@ -315,22 +485,87 @@ export { User } from './user.js';
315
485
 
316
486
  **Rules for `*.browser.runtime.tsx` files:**
317
487
 
318
- - Must not import Node.js modules (`fs`, `path`, server-only libraries) by value. Use `import type` if only the type is needed.
488
+ - Must not import Node.js modules (fs, path, server-only libraries) by value. Use `import type` if only the type is needed.
489
+
490
+ ---
491
+
492
+ ## Deploying
493
+
494
+ **There is nothing to configure.** Exporting is deploying: Ripple CI builds the exported components, detects the app framework from the build artifacts, and deploys to a managed container automatically. Never add a deployer config or tell the user to set one up.
495
+
496
+ ```bash
497
+ bit ripple log # build status (auto-detects the current lane)
498
+ bit ripple errors # why a build failed
499
+ bit ripple retry # retry a failed job
500
+ ```
501
+
502
+ **Give the user the build link as soon as you have it.** Right after `bit export` returns, run `bit ripple log` to pick up the job and post the link it prints — don't sit silently through the build and don't wait for it to go green. The user can watch progress themselves, and if it fails they already have the page open.
503
+
504
+ Copy that URL verbatim; never assemble one by hand. Its last segment is the job's slug, not the display name, so a hand-built link lands on "No CI job found".
505
+
506
+ Then report the outcome once it finishes. Once the build succeeds, an app that defines a deployment is live — get its URL with the `list_apps` MCP tool, don't guess or construct it:
507
+
508
+ | Exported from | Served on |
509
+ | ----------------- | ---------------- |
510
+ | A lane (staging) | `*.bit-app.dev` |
511
+ | main (production) | `*.composed.app` |
512
+
513
+ **The URL changes when a change request is merged.** The lane's `bit-app.dev` URL is not the production one — after a release, call `list_apps` again and give the user the new `composed.app` URL. Component-only releases have no URL at all, and neither does an app that defines no deployment — a green build on its own is not proof that anything was deployed. If `list_apps` gives you no URL, say so rather than implying the app is live, and point the user at the scope page instead.
514
+
515
+ Custom domains are a Bit Cloud settings flow with no CLI equivalent — send the user to `https://bit.cloud/<owner>/~settings/deployment`. Never claim to have connected a domain yourself.
516
+
517
+ ---
518
+
519
+ ## Troubleshooting
520
+
521
+ ### The app doesn't reflect your change
522
+
523
+ **Most likely the `dist/` is stale.** Consumers import a component through `node_modules/<package>/dist/`, not its source, and `bit validate` type-checks _source_ — so it passes green while the running app still serves the old build. `bit watch` / `bit start` normally recompiles on save, but if either isn't running, or the change landed while it was down, the old `dist/` sits there.
524
+
525
+ ```bash
526
+ bit compile # rebuild dist/
527
+ # then restart the app
528
+ ```
529
+
530
+ Do this **before** re-reading and re-editing files. If the source is already correct, editing it again cannot help — a passing `bit validate` plus wrong runtime behavior is the signature of this bug, not of a code error.
531
+
532
+ If compiling and restarting doesn't help, run `bit install`, then restart again.
533
+
534
+ ### Seeded or mock data doesn't update
535
+
536
+ Seed logic usually writes only into an empty collection, so changing a seed or a `*.model.ts` has no effect on a database that already has rows — the stale documents stay, and may not even match the new shape. Clear the affected collections before restarting, or version the seed (write a marker document and re-seed when the version changes) so it re-runs on its own.
537
+
538
+ ### GraphQL data missing or malformed
539
+
540
+ The backend schema and the query the frontend sends have drifted apart. Compare the two directly; don't debug the UI.
541
+
542
+ ### Apollo test imports fail to resolve
543
+
544
+ `@apollo/client/testing` is the normal import and works on most versions. Only when it genuinely fails to resolve, import from `@apollo/client/testing/react/index.js` instead — don't rewrite an import that already works.
319
545
 
320
546
  ---
321
547
 
322
548
  ## Common Mistakes to Avoid
323
549
 
324
- | Mistake | Correct approach |
325
- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
326
- | Creating multiple components upfront | Create one, validate, then decide what's next |
327
- | Modifying an installed (node_modules) component | Import it with `bit import` first |
328
- | Importing only the target component but not its dependents | Import the full chain top-down: platform → app → feature → page → component |
329
- | Treating all components as UI widgets | Understand the type first — platform, app, feature/aspect, hook, entity, or UI component — it determines the chain |
330
- | Running `bit build` | Use `bit validate` instead — faster and sufficient |
331
- | Pushing to the main lane | Always create a lane, snap, then export |
332
- | Using git to version components | Bit manages component versions — use `bit snap` / `bit export` |
333
- | Guessing a component ID | Check `package.json` under `componentId` or use `bit list` |
334
- | Creating a component that already exists | Always run `bit list` and check the Bit Cloud MCP (`read_scopes` / `search`) first |
335
- | Using `npm install`, `yarn`, or `pnpm` | Use `bit install` |
336
- | Using `tsc` or `npx tsc` to check types | Use `bit validate`, `bit check-types`, or `bit test` |
550
+ | Mistake | Correct approach |
551
+ | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
552
+ | Creating multiple components upfront | Create one, validate, then decide what's next |
553
+ | Modifying an installed (node_modules) component | Import it with `bit import` first |
554
+ | Importing only the target component but not its dependents | Import the full chain top-down: platform → app → feature → page → component |
555
+ | Treating all components as UI widgets | Understand the type first — platform, app, feature/aspect, or UI component — it determines the chain |
556
+ | Running `bit build` | Use `bit validate` instead |
557
+ | Pushing to main lane | Always create a lane, snap, then export |
558
+ | Using git for version control | Bit only — no git in the workspace |
559
+ | Guessing a component ID | Check `package.json` under `componentId` or use `bit list` |
560
+ | Creating a component that already exists | Always `bit list` and search MCP first |
561
+ | Using `npm install`, `yarn`, or `pnpm` | Use `bit install` to install packages |
562
+ | Using `tsc` or `npx tsc` to check types | Use `bit validate`, `bit check-types`, or `bit test` |
563
+ | Trying to create a scope from the CLI | Scopes only exist on Bit Cloud — use the `create_scope` MCP tool |
564
+ | Creating a scope for a domain that already has one | Run `read_scope` / `list_components` first — reuse the existing scope |
565
+ | Creating a scope up front, before any code exists | Create it right before `bit export` — that's the only point it must exist |
566
+ | Creating a scope without asking | Confirm the name, owner and visibility with the user; on paid plans preview first, then call again with `confirmed: true` |
567
+ | Exporting, then going quiet during the build | Post the Ripple CI job link as soon as `bit export` returns, then report the result |
568
+ | Continuing to snap onto a lane that was already released | `bit switch main`, then `bit lane create` for the next piece of work |
569
+ | Making the platform import a feature aspect | Inverted — the feature aspect imports the platform and registers itself |
570
+ | Importing React/SCSS in a node runtime, or Node.js modules in a browser runtime | Keep runtime code on its own side of the boundary and out of `index.ts` |
571
+ | Hand-writing a platform, aspect or app | Scaffold it with `bit create` — run `bit templates` to see what's available |
package/package.json CHANGED
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "name": "@teambit/host-initializer",
3
- "version": "0.0.870",
3
+ "version": "0.0.871",
4
4
  "homepage": "https://bit.cloud/teambit/harmony/host-initializer",
5
5
  "main": "dist/index.js",
6
6
  "componentId": {
7
7
  "scope": "teambit.harmony",
8
8
  "name": "host-initializer",
9
- "version": "0.0.870"
9
+ "version": "0.0.871"
10
10
  },
11
11
  "dependencies": {
12
12
  "lodash": "4.17.21",
@@ -32,7 +32,7 @@
32
32
  "@teambit/legacy-bit-id": "1.1.3",
33
33
  "@teambit/legacy.constants": "0.0.43",
34
34
  "@teambit/legacy.scope-api": "0.0.215",
35
- "@teambit/objects": "0.0.664"
35
+ "@teambit/objects": "0.0.665"
36
36
  },
37
37
  "devDependencies": {
38
38
  "@types/lodash": "4.14.165",