claude-toolkit 0.15.0 → 0.17.0-rc.1

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 (70) hide show
  1. package/CHANGELOG.md +30 -0
  2. package/README.md +55 -14
  3. package/bin/cli.ts +75 -19
  4. package/core/skills/ct-typescript-conventions/SKILL.md +59 -1
  5. package/package.json +6 -7
  6. package/src/generator.ts +66 -27
  7. package/src/refresh-hint.ts +95 -0
  8. package/templates/skill-rules.base.json +29 -6
  9. package/bin/postinstall.mjs +0 -69
  10. package/docs/README.md +0 -59
  11. package/docs/agents/code-reviewer.md +0 -76
  12. package/docs/agents/github-workflow.md +0 -98
  13. package/docs/best-practices/capacitor/README.md +0 -64
  14. package/docs/best-practices/capacitor/capacitor-8.md +0 -60
  15. package/docs/best-practices/capacitor/capgo-setup.md +0 -151
  16. package/docs/best-practices/capacitor/channels-and-rollouts.md +0 -101
  17. package/docs/best-practices/capacitor/live-updates-ota.md +0 -75
  18. package/docs/best-practices/capacitor/security-encryption.md +0 -68
  19. package/docs/best-practices/solidjs/README.md +0 -43
  20. package/docs/best-practices/solidjs/anti-patterns.md +0 -166
  21. package/docs/best-practices/solidjs/component-patterns.md +0 -131
  22. package/docs/best-practices/solidjs/context-and-global-state.md +0 -131
  23. package/docs/best-practices/solidjs/control-flow.md +0 -124
  24. package/docs/best-practices/solidjs/data-fetching.md +0 -205
  25. package/docs/best-practices/solidjs/effects-and-lifecycle.md +0 -113
  26. package/docs/best-practices/solidjs/performance.md +0 -100
  27. package/docs/best-practices/solidjs/props-patterns.md +0 -100
  28. package/docs/best-practices/solidjs/reactivity-model.md +0 -104
  29. package/docs/best-practices/solidjs/signals-and-state.md +0 -78
  30. package/docs/best-practices/solidjs/stores-and-nested-state.md +0 -111
  31. package/docs/best-practices/solidjs/typescript-integration.md +0 -186
  32. package/docs/best-practices/testing/README.md +0 -84
  33. package/docs/best-practices/testing/playwright-e2e.md +0 -649
  34. package/docs/best-practices/testing/storybook-interaction.md +0 -455
  35. package/docs/best-practices/testing/vitest-unit.md +0 -451
  36. package/docs/best-practices/typescript/README.md +0 -45
  37. package/docs/best-practices/typescript/any-and-unknown.md +0 -73
  38. package/docs/best-practices/typescript/deriving-vs-decoupling.md +0 -83
  39. package/docs/best-practices/typescript/discriminated-unions.md +0 -75
  40. package/docs/best-practices/typescript/enums-alternatives.md +0 -72
  41. package/docs/best-practices/typescript/essential-patterns.md +0 -119
  42. package/docs/best-practices/typescript/generics-patterns.md +0 -105
  43. package/docs/best-practices/typescript/micro-opinions.md +0 -87
  44. package/docs/best-practices/typescript/runtime-validation.md +0 -62
  45. package/docs/best-practices/typescript/satisfies-operator.md +0 -100
  46. package/docs/best-practices/typescript/tsconfig-cheat-sheet.md +0 -129
  47. package/docs/best-practices/typescript/type-organization.md +0 -64
  48. package/docs/best-practices/typescript/type-vs-interface.md +0 -80
  49. package/docs/commands/code-quality.md +0 -36
  50. package/docs/commands/onboard.md +0 -63
  51. package/docs/commands/pr-review.md +0 -91
  52. package/docs/commands/pr-summary.md +0 -50
  53. package/docs/commands/proto-check.md +0 -59
  54. package/docs/commands/ticket.md +0 -56
  55. package/docs/skills/code-style.md +0 -26
  56. package/docs/skills/systematic-debugging.md +0 -70
  57. package/docs/skills/testing-patterns.md +0 -140
  58. package/docs/skills/typescript-conventions.md +0 -191
  59. package/docs/skills/verification-before-completion.md +0 -103
  60. package/docs/stacks/capacitor-ota.md +0 -145
  61. package/docs/stacks/cloudflare-d1-kv.md +0 -144
  62. package/docs/stacks/esnext-idioms.md +0 -25
  63. package/docs/stacks/i18n-typesafe.md +0 -141
  64. package/docs/stacks/playwright-patterns.md +0 -179
  65. package/docs/stacks/protobuf-contracts.md +0 -85
  66. package/docs/stacks/rust-wasm-patterns.md +0 -106
  67. package/docs/stacks/solidjs-patterns.md +0 -110
  68. package/docs/stacks/storybook-patterns.md +0 -177
  69. package/docs/stacks/vanilla-extract-patterns.md +0 -115
  70. package/docs/stacks/vite-vitest-patterns.md +0 -485
@@ -1,151 +0,0 @@
1
- # Capgo Setup & API
2
-
3
- > `@capgo/capacitor-updater` ships in three modes: fully managed (Capgo Cloud), self-hosted (your own update server), or manual (you drive every download/apply in JS). This guide covers the managed path and the manual escape hatch.
4
-
5
- ## Install
6
-
7
- ```bash
8
- npm i @capgo/capacitor-updater && npx cap sync
9
- npx @capgo/cli@latest init <API_KEY>
10
- ```
11
-
12
- `init` is an interactive onboarding: it registers the app in Capgo Cloud, injects the `notifyAppReady()` call, builds, uploads the first bundle, and verifies the update round-trips. Run it once per app.
13
-
14
- ## notifyAppReady() — Read This First
15
-
16
- ```typescript
17
- import { CapacitorUpdater } from "@capgo/capacitor-updater";
18
-
19
- // As early as possible in bootstrap, before heavy async work.
20
- CapacitorUpdater.notifyAppReady();
21
- ```
22
-
23
- The plugin arms a timer (`appReadyTimeout`, default **10000ms**) the moment a bundle loads. Call `notifyAppReady()` before it fires and the bundle is confirmed; miss it and the plugin **auto-rolls back** to the previous bundle. This is the mechanism that makes a broken release self-heal — never remove it, and don't bury it behind slow startup code.
24
-
25
- ## Configuration Reference
26
-
27
- ```typescript
28
- // capacitor.config.ts
29
- import type { CapacitorConfig } from "@capacitor/cli";
30
-
31
- const config: CapacitorConfig = {
32
- appId: "com.example.app",
33
- appName: "Example",
34
- webDir: "dist",
35
- plugins: {
36
- CapacitorUpdater: {
37
- autoUpdate: "atBackground",
38
- appReadyTimeout: 10000,
39
- responseTimeout: 20,
40
- autoDeleteFailed: true,
41
- autoDeletePrevious: true,
42
- resetWhenUpdate: true,
43
- // defaultChannel: "Development", // TEST/QA BUILDS ONLY
44
- // publicKey: "...", // injected by `key create` for E2E encryption
45
- },
46
- },
47
- };
48
-
49
- export default config;
50
- ```
51
-
52
- | Setting | Default | Purpose |
53
- | -------------------- | -------------------------------------- | ------------------------------------------------------------ |
54
- | `autoUpdate` | `"atBackground"` | When to apply downloaded updates (see table below) |
55
- | `appReadyTimeout` | `10000` (ms) | Grace period for `notifyAppReady()` before rollback |
56
- | `responseTimeout` | `20` (s) | Update-server API call timeout |
57
- | `periodCheckDelay` | `600` (s) | Poll interval; **cannot be < 600** |
58
- | `autoDeleteFailed` | `true` | Remove bundles that failed to apply |
59
- | `autoDeletePrevious` | `true` | Remove the prior bundle after a successful update |
60
- | `resetWhenUpdate` | `true` | Wipe OTA bundles when the native app updates |
61
- | `defaultChannel` | _(unset)_ | Pin a channel — **test builds only** |
62
- | `allowModifyUrl` | `false` | Let JS change update/stats/channel URLs at runtime |
63
- | `publicKey` | _(unset)_ | RSA public key for end-to-end encryption (v2) |
64
- | `updateUrl` | `https://plugin.capgo.app/updates` | Update-check endpoint (override for self-hosted) |
65
- | `statsUrl` | `https://plugin.capgo.app/stats` | Stats endpoint |
66
- | `channelUrl` | `https://plugin.capgo.app/channel_self`| Channel self-assignment endpoint |
67
-
68
- > `directUpdate` is deprecated. Use the `autoUpdate` string modes instead.
69
-
70
- ## autoUpdate Modes
71
-
72
- | Value | Behavior |
73
- | ---------------------------- | -------------------------------------------------------------- |
74
- | `false` / `"off"` | No automatic updates — you drive the lifecycle from JS |
75
- | `"atBackground"` *(default)* | Download silently; apply when the app moves to the background |
76
- | `"atInstall"` | Apply immediately after a fresh install / native update |
77
- | `"onLaunch"` | Apply immediately on next launch, then revert to background |
78
- | `"always"` | Apply immediately whenever an update check runs |
79
- | `"onlyDownload"` | Download but never auto-apply; emits `updateAvailable` |
80
-
81
- **Default lifecycle:** on launch Capgo checks the channel → downloads any new bundle silently → waits for background/close → user gets the update on next launch. Seamless, no spinner.
82
-
83
- ## Manual Mode
84
-
85
- Set `autoUpdate: false` to control everything yourself — useful for custom UX (e.g. "Update available" prompts) or applying only on explicit user action.
86
-
87
- ```typescript
88
- import { CapacitorUpdater } from "@capgo/capacitor-updater";
89
- import { App } from "@capacitor/app";
90
- import { SplashScreen } from "@capacitor/splash-screen";
91
-
92
- CapacitorUpdater.addListener("download", ({ percent }) => {
93
- console.log(`Downloading: ${percent}%`);
94
- });
95
-
96
- App.addListener("appStateChange", async ({ isActive }) => {
97
- if (isActive) {
98
- const latest = await CapacitorUpdater.getLatest();
99
- if (latest.url) {
100
- const bundle = await CapacitorUpdater.download({
101
- version: latest.version,
102
- url: latest.url,
103
- });
104
- await CapacitorUpdater.next({ id: bundle.id }); // queue for next background
105
- }
106
- }
107
- });
108
- ```
109
-
110
- ### Core methods
111
-
112
- | Method | Purpose |
113
- | ----------------- | -------------------------------------------------------------- |
114
- | `notifyAppReady()`| Confirm the current bundle booted (always required) |
115
- | `getLatest()` | Query the server for the latest bundle metadata |
116
- | `download()` | Download a bundle by `{ version, url }` |
117
- | `next({ id })` | Queue a bundle to apply on next background |
118
- | `set({ id })` | Apply a bundle now — **destroys the JS context** (hard reload) |
119
- | `current()` | Inspect the active bundle + native version |
120
- | `reload()` | Apply a pending update without backgrounding |
121
- | `reset()` | Revert to the bundle baked into the native binary |
122
- | `setChannel()` | Switch the device's channel at runtime (v8+, self-assign) |
123
-
124
- ### Events
125
-
126
- `download` · `downloadComplete` · `updateAvailable` · `downloadFailed` · `appReady` · `majorAvailable`
127
-
128
- Subscribe to `downloadFailed` and `appReady` for monitoring; subscribe to `majorAvailable` to detect a bundle that requires a native update you can't OTA.
129
-
130
- ## CLI Cheat Sheet
131
-
132
- ```bash
133
- npx @capgo/cli@latest login <API_KEY> # store key (--local to scope to repo)
134
- npx @capgo/cli@latest app add com.example.app # register an app
135
- npx @capgo/cli@latest bundle upload --channel=production # build → upload → assign
136
- npx @capgo/cli@latest bundle upload --key-v2 --channel=production # encrypted upload
137
- npx @capgo/cli@latest bundle upload --delta-only # require delta-capable clients
138
- npx @capgo/cli@latest bundle compatibility -c production # check native compatibility first
139
- npx @capgo/cli@latest channel set production -s default # set the cloud default channel
140
- npx @capgo/cli@latest key create # generate the E2E key pair
141
- ```
142
-
143
- Useful `bundle upload` flags: `--channel`, `--key-v2` / `--no-key`, `--delta` / `--delta-only`, `--external` (link your own storage), `--tus` (resumable upload), `--encrypted-checksum`.
144
-
145
- **Pin the CLI version in CI** (`@capgo/cli@8.x` rather than `@latest`) so upload behavior doesn't change between pipeline runs.
146
-
147
- ## See Also
148
-
149
- - [Channels & Staged Rollouts](channels-and-rollouts.md) — what `--channel` and `setChannel` actually do
150
- - [Security & Encryption](security-encryption.md) — the `--key-v2` flow in full
151
- - [Live Updates & OTA Strategy](live-updates-ota.md) — when to use each `autoUpdate` mode
@@ -1,101 +0,0 @@
1
- # Channels & Staged Rollouts
2
-
3
- > A channel is a pointer to one JS bundle. Devices subscribe to a channel; you change which bundle the channel points to. That indirection is what makes rollout and rollback instant and rebuild-free.
4
-
5
- ## The Channel Ladder
6
-
7
- Mirror your release pipeline with channels, and version bundles with semver pre-release tags so relationships are obvious:
8
-
9
- | Channel | Bundle version | Audience |
10
- | ------------- | -------------- | ------------------------- |
11
- | `development` | `1.2.3-dev.1` | dev / emulator builds |
12
- | `qa` | `1.2.3-qa.1` | QA verification |
13
- | `staging` | `1.2.3-rc.1` | production-like sign-off |
14
- | `production` | `1.2.3` | end users (store version) |
15
-
16
- Promote a build up the ladder by uploading (or re-pointing) it to the next channel — no native rebuild between stages.
17
-
18
- ```bash
19
- npx @capgo/cli@latest bundle upload --channel=staging # ship to staging
20
- # ...QA signs off...
21
- npx @capgo/cli@latest bundle upload --channel=production # promote to production
22
- npx @capgo/cli@latest channel set production -s default # ensure it's the cloud default
23
- ```
24
-
25
- ## Channel Precedence
26
-
27
- When a device checks for updates, Capgo resolves the channel in this order (highest wins):
28
-
29
- 1. **Forced device mapping** — pin specific device IDs (testing/exception layer).
30
- 2. **Cloud per-device override** — dashboard/API change for one device (up to ~2 min to propagate).
31
- 3. **Config `defaultChannel`** — set in `capacitor.config` (baked into the binary).
32
- 4. **Cloud Default Channel** — the fallback ~99% of users follow.
33
-
34
- **Production rule:** ship production binaries **without** `defaultChannel`. If you bake a channel into the binary, those users stop following the cloud default — which is exactly the lever you use for instant rollout and rollback. Reserve `defaultChannel` for builds you hand directly to testers.
35
-
36
- ## Runtime Switching with setChannel()
37
-
38
- Let users opt into a beta from inside the app:
39
-
40
- ```typescript
41
- import { CapacitorUpdater } from "@capgo/capacitor-updater";
42
-
43
- await CapacitorUpdater.setChannel({ channel: "beta", triggerAutoUpdate: true });
44
- ```
45
-
46
- - Requires **"Allow device self-assignment"** enabled on the target channel; otherwise the call fails.
47
- - In **plugin v8+**, `setChannel` stores the choice **locally on the device** and takes effect on the next update check — no 2-minute backend replication lag. The backend still validates the self-assignment permission at check time.
48
-
49
- ```bash
50
- npx @capgo/cli@latest channel set beta --self-assign # enable opt-in
51
- ```
52
-
53
- ## Version Gates: Enforce the Native/Web Contract
54
-
55
- Channels can refuse updates that cross a version boundary the native shell can't honor:
56
-
57
- ```bash
58
- # Block cross-major OTA on production (e.g. don't push a 2.x bundle to 1.x shells)
59
- npx @capgo/cli@latest channel set production --disable-auto-update major
60
- ```
61
-
62
- | `--disable-auto-update` | Allows |
63
- | ----------------------- | --------------------------------------------------- |
64
- | `major` | minor + patch within the same major |
65
- | `minor` | patch only within the same major.minor |
66
- | `patch` | patch increments only |
67
- | `metadata` | requires minimum version metadata on bundles |
68
- | `none` | all semver-compatible updates |
69
-
70
- Also available: **disable auto-downgrade** (don't send a bundle older than the device's native version) and per-platform targeting (`--ios`, `--android`). These gates are how you keep a web bundle from landing on a shell that can't run it.
71
-
72
- ## Staged Rollout Playbook
73
-
74
- 1. **Canary** — point the channel at the new bundle for ~10% of users (or a dedicated `canary` channel).
75
- 2. **Observe** — watch the success signal for 1–2 hours (next section).
76
- 3. **Widen** — ramp to 100% over ~24h if healthy.
77
- 4. **Schedule** — time heavy rollouts for **1–4 AM local**, Wi-Fi-preferred, so downloads don't compete with active use.
78
-
79
- **Benchmarks:** aim for **~95% adoption within 24h** and **~82% global success rate**. Falling short is a signal to pause and investigate, not to widen.
80
-
81
- ## Rollback
82
-
83
- Instant and rebuild-free — the core OTA payoff:
84
-
85
- 1. Open the channel in the Capgo dashboard.
86
- 2. Find the previous good build and click the **crown icon**.
87
- 3. Confirm. The channel now points at the old bundle; devices pick it up on next check-in.
88
-
89
- Because rollback is this cheap, bias toward shipping small and reverting fast over holding releases for exhaustive pre-launch testing.
90
-
91
- ## Monitoring
92
-
93
- - **`appReady` vs `downloadFailed`** — the health ratio. A `downloadFailed` spike, or `appReady` events not keeping pace with downloads, means bundles are failing to boot → roll back.
94
- - **Capgo stats dashboard** — adoption curve and per-version success rate. Compare against the 95% / 82% benchmarks.
95
- - **Alert, then act** — wire a threshold alert so a bad canary pages you before you widen.
96
-
97
- ## See Also
98
-
99
- - [Live Updates & OTA Strategy](live-updates-ota.md) — why staged rollout is the whole point
100
- - [Capacitor 8 Platform](capacitor-8.md) — what makes a bundle native-incompatible
101
- - [Security & Encryption](security-encryption.md) — signing the bundles a channel serves
@@ -1,75 +0,0 @@
1
- # Live Updates & OTA Strategy
2
-
3
- > OTA is a delivery mechanism for the **web layer**, not a way around the app stores. The strategy is mostly about discipline: knowing what you can ship over the air, keeping bundles small, and rolling out so a mistake is recoverable.
4
-
5
- ## What You Can — and Cannot — Ship Over the Air
6
-
7
- | Change | OTA? | Why |
8
- | ----------------------------------------------- | ---- | ----------------------------------------------------------- |
9
- | Bug fix in JS/TS | ✅ | Pure web layer |
10
- | Copy, translations, styling | ✅ | Static assets in the bundle |
11
- | New feature built on existing native APIs | ✅ | No new native contract |
12
- | Web-only dependency upgrade | ✅ | Compiles into the bundle |
13
- | New Capacitor **plugin** (native code) | ❌ | Native shell lacks the implementation → crash |
14
- | Native dependency / SDK upgrade | ❌ | Native binary change |
15
- | Capacitor **major** version bump | ❌ | Native runtime change |
16
- | Permission / entitlement / manifest change | ❌ | Declared in the native binary |
17
-
18
- The failure mode is concrete: a bundle that calls `SomePlugin.doThing()` on a shell where that plugin isn't compiled in throws at runtime. **Match every bundle to the native version that can run it.**
19
-
20
- ## Store Compliance
21
-
22
- OTA of interpreted code is explicitly permitted:
23
-
24
- - **Apple** — Developer Agreement **§3.3.2** allows OTA of JavaScript and assets executed by the system WebView (since iOS 4.3).
25
- - **Google Play** — the restriction on non-Play code updates **does not apply** to code running in a VM with limited API access, i.e. JavaScript in a WebView.
26
-
27
- What gets apps pulled is shipping *native* executable code OTA. Stay in the web layer and you stay compliant.
28
-
29
- ## Performance: Keep Bundles Small
30
-
31
- Smaller bundles download faster, fail less, and adopt quicker.
32
-
33
- - **Delta / differential updates.** Capgo transfers only the files that changed between versions (auto-enabled with direct/instant updates). The win depends on file-level stability — see below.
34
- - **Deterministic builds.** Strip build timestamps and pin your build tooling so unchanged source produces byte-identical output. Otherwise every file looks "changed" and the delta degrades to a full download.
35
- - **Compression.** Capgo applies ZSTD compression to full-image updates; you don't configure it, but deterministic builds are what let delta + compression actually shrink the payload.
36
- - **Prioritize the critical path.** Load auth and main navigation eagerly; lazy-load analytics, settings, animations, and heavy media after first paint. A small critical bundle reaches `notifyAppReady()` faster, which matters because of the rollback timeout.
37
-
38
- ## Update Timing & Scheduling
39
-
40
- - **Off-peak rollouts.** Schedule heavy rollouts for **1–4 AM local time** and prefer Wi-Fi so you're not competing with active use or burning cellular data.
41
- - **Background application.** The default `atBackground` mode downloads silently and applies when the app backgrounds, so users never watch a spinner. Reserve `onLaunch` / `always` for updates that must take effect immediately (e.g. a hotfix).
42
- - **Respect `periodCheckDelay`.** Minimum 600s (10 min). Don't try to poll faster — it's clamped.
43
-
44
- ## Roll Out So You Can Roll Back
45
-
46
- The whole point of OTA is that mistakes are cheap to undo. Treat every release as staged:
47
-
48
- 1. **Canary** to ~10% of users.
49
- 2. **Watch** the success signal (`appReady` vs `downloadFailed`, Capgo stats) for 1–2 hours.
50
- 3. **Widen** to 100% over ~24h if healthy.
51
- 4. **Roll back instantly** from the channel dashboard if not — devices pick up the previous bundle on next check-in.
52
-
53
- Healthy benchmarks: **~95% adoption within 24h**, **~82% global success rate**. Below that, investigate before widening.
54
-
55
- ## The notifyAppReady() Safety Net
56
-
57
- This is what makes the above safe. The plugin starts a timer (`appReadyTimeout`, default 10s) when a new bundle loads. If your JS calls `notifyAppReady()` before it fires, the bundle is "confirmed." If it doesn't — because the bundle white-screened or threw on boot — the plugin **automatically reverts** to the last good bundle. A broken OTA release self-heals on the next launch even before you notice.
58
-
59
- Call it as early as possible, before heavy async work, so a slow boot doesn't trip the timeout on an otherwise-fine bundle.
60
-
61
- ## Anti-Patterns
62
-
63
- | Anti-pattern | Consequence |
64
- | ------------------------------------------- | ----------------------------------------------------------------- |
65
- | OTA-ing a native change | Runtime crash on the mismatched shell |
66
- | Non-deterministic builds | Delta updates degrade to full downloads |
67
- | 100% rollout, no canary | A bad bundle hits the entire user base at once |
68
- | Eager-loading everything | Slow boot risks tripping `appReadyTimeout` → false rollback |
69
- | Polling faster than 600s | Silently clamped; wasted assumption |
70
-
71
- ## See Also
72
-
73
- - [Capacitor 8 Platform](capacitor-8.md) — keeping native and OTA in lockstep
74
- - [Capgo Setup & API](capgo-setup.md) — config and the manual update lifecycle
75
- - [Channels & Staged Rollouts](channels-and-rollouts.md) — the mechanics of canarying and rollback
@@ -1,68 +0,0 @@
1
- # Security & Encryption
2
-
3
- > An OTA bundle travels over the network and lands on devices you don't control. End-to-end encryption with code signing makes each update unreadable in transit and verifiable on arrival — only your users can decrypt it, and only your signed bundles are accepted.
4
-
5
- ## Why Encrypt
6
-
7
- A channel controls *who is eligible* for an update; it does **not** keep the bundle secret. An unencrypted bundle should be treated as a public asset. If your web layer contains anything you don't want readable — proprietary logic, embedded config — encryption is the only thing that keeps it private end to end, including from Capgo itself.
8
-
9
- ## How v2 Encryption Works (Hybrid RSA + AES)
10
-
11
- RSA can't efficiently encrypt large payloads, so Capgo uses a hybrid scheme:
12
-
13
- 1. A **random AES-256 key** is generated for every upload and encrypts the bundle.
14
- 2. Your **private RSA-2048 key** encrypts (signs) the AES key and the bundle checksum.
15
- 3. The app holds your **public RSA key** (injected at build) and decrypts the AES key + signature.
16
- 4. The app decrypts the bundle with the AES key, recomputes the checksum, and compares it against the decrypted signature.
17
-
18
- The result: the bundle is confidential (AES) **and** authenticated (RSA signature over the checksum). Tampering breaks the checksum match; a bundle not signed by your private key won't validate.
19
-
20
- > Industry baseline this matches: **AES-256** for payloads, **RSA-2048** for key exchange, **SHA-256** for integrity.
21
-
22
- ## Setup
23
-
24
- ```bash
25
- npx @capgo/cli@latest key create # generate the RSA key pair
26
- npx @capgo/cli@latest bundle upload --key-v2 --channel=production
27
- ```
28
-
29
- `key create` writes two files and injects the public key into your Capacitor config:
30
-
31
- | File | Sensitivity | Rule |
32
- | --------------------- | ----------- | ---------------------------------------------------------- |
33
- | `.capgo_key_v2` | **Private** | **Never commit.** Store as a CI secret. Loss = can't sign. |
34
- | `.capgo_key_v2.pub` | Public | Safe to commit — it's a backup of the embedded public key. |
35
-
36
- Add `.capgo_key_v2` to `.gitignore` immediately. The private key only ever lives on trusted dev machines and in CI secret storage; it's used at upload time to sign, never shipped to devices.
37
-
38
- ## Strict Enforcement
39
-
40
- Once encryption is configured, the plugin **requires** a valid signature on every update — this is enforced, not advisory. An unsigned or tampered bundle is **rejected**, not applied. Practical consequences:
41
-
42
- - Every CI upload must run with `--key-v2` and access to the private key, or devices will reject the bundle.
43
- - Rotating keys requires shipping a new native binary with the new public key; plan it as a store release, not an OTA.
44
- - `--no-key` (unencrypted) and encrypted uploads don't mix on the same channel for the same audience — pick one posture per channel.
45
-
46
- ## Integrity Beyond Encryption
47
-
48
- - **Checksums** verify the decrypted bundle matches what you signed — corruption or tampering fails closed.
49
- - **`notifyAppReady()`** is the runtime backstop: even a validly-signed bundle that crashes on boot rolls back automatically (see [Capgo Setup](capgo-setup.md)). Signing proves *authenticity*; `notifyAppReady` proves *it actually runs*. You want both.
50
-
51
- ## Store Compliance
52
-
53
- Encryption doesn't change what you're allowed to ship — it just protects the payload. The compliance rule is unchanged: OTA of **JavaScript/HTML/CSS** is permitted (Apple Developer Agreement §3.3.2; Google Play's webview/JS-VM exemption). Encrypting that web bundle is fine. Encrypting and shipping *native* executable code OTA is still not allowed — encryption is not a loophole around the native/web boundary.
54
-
55
- ## Checklist
56
-
57
- - [ ] `npx @capgo/cli key create` run; `.capgo_key_v2` added to `.gitignore`.
58
- - [ ] Private key stored as a CI secret; `--key-v2` used on every production upload.
59
- - [ ] `.capgo_key_v2.pub` committed as a backup.
60
- - [ ] `notifyAppReady()` present so signed-but-broken bundles still self-heal.
61
- - [ ] Key rotation planned as a native binary release, not an OTA.
62
- - [ ] Only web-layer code shipped OTA — never native code, encrypted or not.
63
-
64
- ## See Also
65
-
66
- - [Capgo Setup & API](capgo-setup.md) — the upload flow and `publicKey` config
67
- - [Channels & Staged Rollouts](channels-and-rollouts.md) — per-channel encryption posture
68
- - [Live Updates & OTA Strategy](live-updates-ota.md) — what's legal to ship over the air
@@ -1,43 +0,0 @@
1
- # SolidJS Best Practices
2
-
3
- > A curated collection of SolidJS best practices, patterns, and guidance sourced from the [official SolidJS documentation](https://docs.solidjs.com/), [Ryan Carniato](https://dev.to/ryansolid) (SolidJS creator), and the SolidJS community.
4
-
5
- SolidJS uses **fine-grained reactivity** with no virtual DOM. Components run once; only reactive expressions re-execute when dependencies change. This is fundamentally different from virtual DOM frameworks — and most best practices stem from this core difference.
6
-
7
- ## Reactivity
8
-
9
- Understanding reactivity is the foundation of everything in Solid.
10
-
11
- | Guide | Summary |
12
- |---|---|
13
- | [Reactivity Model](reactivity-model.md) | How fine-grained reactivity works — signals, tracking, subscriptions. |
14
- | [Signals & State](signals-and-state.md) | `createSignal`, `createMemo`, derived values, and when to use what. |
15
- | [Stores & Nested State](stores-and-nested-state.md) | `createStore`, path syntax, `produce`, `reconcile` for complex state. |
16
- | [Effects & Lifecycle](effects-and-lifecycle.md) | `createEffect`, `onMount`, `onCleanup` — and when NOT to use effects. |
17
-
18
- ## Components
19
-
20
- Patterns for building and composing components.
21
-
22
- | Guide | Summary |
23
- |---|---|
24
- | [Props Patterns](props-patterns.md) | Never destructure. Use `mergeProps`, `splitProps`, `children` helper. |
25
- | [Component Patterns](component-patterns.md) | Composition, typed components, generic components, refs. |
26
- | [Control Flow](control-flow.md) | `<Show>`, `<For>`, `<Switch>`/`<Match>`, `<ErrorBoundary>`, `<Suspense>`. |
27
-
28
- ## Architecture
29
-
30
- Scaling patterns for real applications.
31
-
32
- | Guide | Summary |
33
- |---|---|
34
- | [Data Fetching](data-fetching.md) | `createResource`, `createAsync`, Suspense, error handling, optimistic updates. |
35
- | [Context & Global State](context-and-global-state.md) | Context + stores pattern, provider factories, avoiding prop drilling. |
36
- | [TypeScript Integration](typescript-integration.md) | Component types, typed signals/stores/context, event handling, TSConfig. |
37
-
38
- ## Performance & Pitfalls
39
-
40
- | Guide | Summary |
41
- |---|---|
42
- | [Performance](performance.md) | `lazy`, `batch`, `untrack`, code splitting, and what Solid optimizes for you. |
43
- | [Anti-Patterns](anti-patterns.md) | The most common mistakes and how to avoid them. |
@@ -1,166 +0,0 @@
1
- # Anti-Patterns
2
-
3
- > Common SolidJS mistakes sourced from the [SolidJS documentation](https://docs.solidjs.com/), community guides, and [Ryan Carniato's articles](https://dev.to/ryansolid).
4
-
5
- ## 1. Destructuring Props
6
-
7
- The single most common Solid mistake. Props use getters for reactivity — destructuring extracts the value once.
8
-
9
- ```typescript
10
- // BROKEN
11
- const Card = ({ title, count }) => <div>{title}: {count}</div>;
12
-
13
- // FIXED
14
- const Card = (props) => <div>{props.title}: {props.count}</div>;
15
- ```
16
-
17
- If you need to separate props, use `splitProps`. If you need defaults, use `mergeProps`.
18
-
19
- ## 2. Forgetting to Call Signals
20
-
21
- Signals are getter functions. Forgetting `()` passes the function itself, not the value.
22
-
23
- ```typescript
24
- // BROKEN — passes the function, not the value
25
- <span>{count}</span>
26
-
27
- // FIXED
28
- <span>{count()}</span>
29
- ```
30
-
31
- ## 3. Reading Signals Outside Reactive Context
32
-
33
- The component body runs once. Reading a signal at the top level captures the initial value — it never updates.
34
-
35
- ```typescript
36
- // BROKEN — layout is assigned once, never reactive
37
- const MyComponent = (props) => {
38
- const layout = props.wide ? "grid" : "list"; // Evaluated once
39
- return <div class={layout}>...</div>;
40
- };
41
-
42
- // FIXED — read in JSX (reactive context)
43
- const MyComponent = (props) => {
44
- return <div class={props.wide ? "grid" : "list"}>...</div>;
45
- };
46
-
47
- // Also fixed — wrap in a function
48
- const MyComponent = (props) => {
49
- const layout = () => props.wide ? "grid" : "list";
50
- return <div class={layout()}>...</div>;
51
- };
52
- ```
53
-
54
- ## 4. Using Effects to Sync State
55
-
56
- Effects that set state from other state create ordering problems and glitchy intermediate renders.
57
-
58
- ```typescript
59
- // BROKEN — effect-based synchronization
60
- const [count, setCount] = createSignal(0);
61
- const [doubled, setDoubled] = createSignal(0);
62
- createEffect(() => setDoubled(count() * 2));
63
-
64
- // FIXED — derivation
65
- const doubled = createMemo(() => count() * 2);
66
- // or: const doubled = () => count() * 2;
67
- ```
68
-
69
- **Rule:** If a value can be computed from reactive sources, derive it.
70
-
71
- ## 5. Using Effects for Data Fetching
72
-
73
- Effects run after render, have no built-in loading/error states, and create race conditions on dependency changes.
74
-
75
- ```typescript
76
- // BROKEN
77
- createEffect(async () => {
78
- const res = await fetch(`/api/${id()}`);
79
- setData(await res.json());
80
- });
81
-
82
- // FIXED
83
- const [data] = createResource(id, fetchData);
84
- ```
85
-
86
- `createResource` integrates with Suspense, handles loading/error, and manages race conditions.
87
-
88
- ## 6. Using `.map()` Instead of `<For>`
89
-
90
- JavaScript `.map()` recreates all DOM nodes whenever the array signal changes. `<For>` tracks items by reference and only updates what changed.
91
-
92
- ```typescript
93
- // INEFFICIENT — full DOM rebuild on any array change
94
- <ul>{items().map(item => <li>{item.name}</li>)}</ul>
95
-
96
- // CORRECT — granular updates
97
- <ul><For each={items()}>{(item) => <li>{item.name}</li>}</For></ul>
98
- ```
99
-
100
- ## 7. Using `&&` for Conditional Rendering
101
-
102
- JavaScript short-circuit evaluation doesn't give Solid the boundaries it needs to optimize.
103
-
104
- ```typescript
105
- // SUBOPTIMAL — no Solid optimization
106
- {isVisible() && <Modal />}
107
-
108
- // CORRECT — Solid can optimize the boundary
109
- <Show when={isVisible()}><Modal /></Show>
110
- ```
111
-
112
- ## 8. Mutating Store State Directly
113
-
114
- Stores use proxies. Direct mutation bypasses the reactive system.
115
-
116
- ```typescript
117
- // BROKEN — Solid doesn't see this change
118
- state.tasks[0].completed = true;
119
-
120
- // FIXED — go through setState
121
- setState("tasks", 0, "completed", true);
122
- ```
123
-
124
- ## 9. Creating Unnecessary Reactivity
125
-
126
- Not everything needs to be a signal. Static configuration, constants, and values that never change don't benefit from reactivity.
127
-
128
- ```typescript
129
- // UNNECESSARY
130
- const [apiUrl] = createSignal("https://api.example.com");
131
-
132
- // JUST USE A CONSTANT
133
- const API_URL = "https://api.example.com";
134
- ```
135
-
136
- ## 10. Missing `onCleanup`
137
-
138
- Effects that create subscriptions, timers, or event listeners without cleanup cause memory leaks.
139
-
140
- ```typescript
141
- // LEAKS — interval is never cleared
142
- createEffect(() => {
143
- setInterval(() => tick(), 1000);
144
- });
145
-
146
- // FIXED
147
- createEffect(() => {
148
- const id = setInterval(() => tick(), 1000);
149
- onCleanup(() => clearInterval(id));
150
- });
151
- ```
152
-
153
- ## Quick Reference
154
-
155
- | Mistake | Fix |
156
- |---|---|
157
- | Destructure props | Use `props.x` directly |
158
- | `count` without `()` | Always call signal getters |
159
- | Signal read at top level | Read in JSX or wrap in `() =>` |
160
- | Effect sets state from state | Use `createMemo` |
161
- | Effect fetches data | Use `createResource` |
162
- | `.map()` for lists | Use `<For>` |
163
- | `&&` for conditionals | Use `<Show>` |
164
- | Direct store mutation | Use `setState()` |
165
- | Signal for constants | Use a plain variable |
166
- | No `onCleanup` | Always clean up side effects |