migrate-waniwani-sdk-0.25-to-1.0
Skill18 starsChanged 8 days agoMITView on GitHub
Migrate a project from @waniwani/sdk 0.25.x to 1.0.x. 1.0 removes the chat widget from @waniwani/sdk. The chat ships only in its own package, @waniwani/chat: `@waniwani/sdk/chat` imports become `@waniwani/chat`, `@waniwani/sdk/chat/styles.css` becomes `@waniwani/chat/styles.css`, and a self-hosted `@waniwani/sdk/dist/chat/embed.js` becomes `@waniwani/chat/dist/embed.js`. Trigger when the user is on 0.25.x and wants 1.0, or after bumping sees `Cannot find module '@waniwani/sdk/chat'`, `Missing \"./chat\" specifier in \"@waniwani/sdk\" package`, `Package subpath './chat' is not defined by \"exports\"`, `Package path ./chat is not exported from package`, or the browser console warning `@waniwani/sdk/dist/chat/embed.js is deprecated`.
In this repository28 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- agent-browserSkill
- copySkill
- deploy-prodSkill
- linear-oneshotSkill
- project-planningSkill
- project-updateSkill
- pull-requestSkill
- wani-code-reviewSkill
- create-flow-appSkill
- frontend-designSkill
- knowledge-baseSkill
- release-migrationSkill
- transfer-to-kitSkill
- translationsSkill
- visualize-flowSkill
- audit-trackingSkill
- instrument-trackingSkill
- migrate-waniwani-sdk-0.15-to-0.16Skill
- migrate-waniwani-sdk-0.16-to-0.17Skill
- migrate-waniwani-sdk-0.17-to-0.18Skill
- migrate-waniwani-sdk-0.18-to-0.19Skill
- migrate-waniwani-sdk-0.19-to-0.20Skill
- migrate-waniwani-sdk-0.22-to-0.23Skill
- migrate-waniwani-sdk-0.23-to-0.24Skill
- migrate-waniwani-sdk-0.24-to-0.25Skill
- waniwani-sdkSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 44
Bump the SDK: Use the project's package manager (bun shown).
- Distinctive: line 53
No hit in the first command: the project does not use the chat.
- Very specific: line 98
Drop
@waniwani/sdkwhen only the chat used it: Run rg -n "@waniwani/sdk" --glob '!node_modules' --glob '!*.lock' --glob … - Very specific: line 107
When the project builds a web app (Next.js, Vite), run its build too.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Migrate @waniwani/sdk 0.25 → 1.0
A self-contained migration for the hop to 1.0.x. For other version boundaries use the matching migrate-waniwani-sdk-<from>-to-<to> skill, or the general procedure in the SDK's changelog.
Precondition: the project is on @waniwani/sdk@0.25.x. On an older version, migrate up to 0.25 first.
A project that never uses the chat widget has nothing to migrate. Bump the dependency, run the completion check, and stop. Step 2 below tells you which case you are in.
What 1.0 changes
@waniwani/sdk 1.0 contains no chat code. The chat widget (WaniwaniChat, ChatEmbed, the themes, styles.css and embed.js) ships only in @waniwani/chat, which is also at 1.0. @waniwani/sdk keeps the server side: flows, the KV stores, tracking, the knowledge base, documents, withWaniwani and useWaniwani. An MCP server that only uses createFlow now installs 0.9 MB instead of 32 MB.
@waniwani/chat exports the same 31 names that @waniwani/sdk/chat exported in 0.25, with the same types and the same behavior. Only the import path moves.
From 1.0, both packages follow semver. A minor or a patch release does not break the public API.
| 0.25 path | 1.0 path | What the 0.25 path does in 1.0 |
@waniwani/sdk/chat | @waniwani/chat | Removed. The build fails |
@waniwani/sdk/chat/styles.css | @waniwani/chat/styles.css | Removed. The build fails |
@waniwani/sdk/chat/embed.js, node_modules/@waniwani/sdk/dist/chat/embed.js | @waniwani/chat/embed.js, node_modules/@waniwani/chat/dist/embed.js | A forwarder that loads @waniwani/chat@1 from jsDelivr and logs a deprecation warning. 2.0.0 removes it |
cdn.jsdelivr.net/npm/@waniwani/sdk@latest/dist/chat/embed.js (or @1, @1.x) | The dashboard snippet, which loads https://app.waniwani.ai/embed.js (EU: https://eu.app.waniwani.ai/embed.js) | The same forwarder |
cdn.jsdelivr.net/npm/@waniwani/sdk@0.<x>.<y>/dist/chat/embed.js | The dashboard snippet | Nothing changes. A pinned 0.x URL keeps its old bundle and never gets fixes |
Breaking, and visible to the build: every @waniwani/sdk/chat import and the @waniwani/sdk/chat/styles.css path. tsc or the bundler stops with one of the errors named in this skill's description.
Not breaking:
- Script-tag sites that use the dashboard snippet. The snippet loads
app.waniwani.ai/embed.js, a loader that picks the current chat bundle. Nothing on the page changes. - Script tags on the old CDN path. The forwarder adds a script tag for
https://cdn.jsdelivr.net/npm/@waniwani/chat@1/dist/embed.jswith the samedata-*attributes, so the chat keeps loading. It costs one more request and logs a warning in the browser console. Move these tags to the dashboard snippet now (step 4). @ai-sdk/mcp.@waniwani/sdkno longer lists it as an optional peer. Nothing in the SDK imported it. A project that installed it only for the SDK can remove it.- Peer dependencies of the chat.
@waniwani/chatneedsreact,ai,@ai-sdk/reactandzod, the same packages the chat needed inside@waniwani/sdk. npm 7 and later, pnpm and bun install missing peers. - Tracking.
createFrontendClient,EVENT_TYPESanduseWaniwanistay in@waniwani/sdk. The chat'strackandidentifykeep the same shape.
Procedure
- Bump the SDK. Use the project's package manager (bun shown).
bun add @waniwani/sdk@^1.0.0 - Collect the chat call sites.
No hit in the first command: the project does not use the chat. Skip to step 6.rg -n "@waniwani/sdk/chat|@waniwani/sdk/dist/chat|@waniwani/sdk@[^/\"' ]*/dist/chat" --glob '!node_modules' --glob '!*.lock' --glob '!package-lock.json' rg -n "@waniwani/sdk" -g 'next.config.*' -g 'vite.config.*' -g 'jest.config.*' -g 'vitest.config.*' -g 'tsconfig*.json' - Install the chat.
bun add @waniwani/chat@^1.0.0 Rewrite every hit with the rules below. Each one is a plain text replacement.
Match Replace with "@waniwani/sdk/chat"in animport,export … from,import(),require(),vi.mock(),jest.mock()ormock.module()"@waniwani/chat"@waniwani/sdk/chat/styles.cssin a JS import or a CSS@import@waniwani/chat/styles.css@waniwani/sdk/chat/embed.js@waniwani/chat/embed.js@waniwani/sdk/dist/chat/embed.js, for example in a copy step or a static route@waniwani/chat/dist/embed.js(thechat/folder is gone from the path)"@waniwani/sdk"intranspilePackages,optimizePackageImports,serverExternalPackages, a JestmoduleNameMapperor atsconfigpathsentry that exists for the chatAdd "@waniwani/chat"next to it. Keep"@waniwani/sdk"when other code still imports itA <script src>withcdn.jsdelivr.net/npm/@waniwani/sdk@…/dist/chat/embed.jsand adata-tokenhttps://app.waniwani.ai/embed.js, orhttps://eu.app.waniwani.ai/embed.jsfor an EU project. Keep everydata-*attribute as it isThe same tag with no data-token, which the page starts withwindow.WaniWani.chat.init()https://cdn.jsdelivr.net/npm/@waniwani/chat@1/dist/embed.js. Keep everydata-*attribute as it isNamed imports stay the same. Do not rename
WaniwaniChat,ChatEmbed,ChatHandle,ChatThemeor any other symbol.// Before import { WaniwaniChat, type ChatHandle } from "@waniwani/sdk/chat"; import "@waniwani/sdk/chat/styles.css"; // After import { WaniwaniChat, type ChatHandle } from "@waniwani/chat"; import "@waniwani/chat/styles.css";<!-- Before --> <script src="https://cdn.jsdelivr.net/npm/@waniwani/sdk@latest/dist/chat/embed.js" data-token="wwp_..." data-channel-id="..." ></script> <!-- After --> <script src="https://app.waniwani.ai/embed.js" data-token="wwp_..." data-channel-id="..." ></script>- Drop
@waniwani/sdkwhen only the chat used it. Runrg -n "@waniwani/sdk" --glob '!node_modules' --glob '!*.lock' --glob '!package-lock.json'. When the only hit left is thepackage.jsondependency line, remove the dependency:
Then removebun remove @waniwani/sdk@ai-sdk/mcpthe same way if nothing imports it (rg -n "@ai-sdk/mcp" --glob '!node_modules'). - Verify, which is the completion check.
When the project builds a web app (Next.js, Vite), run its build too. A stylesheet path that does not resolve fails there, not inbun run typecheck && bun testtsc. - Report each file you rewrote, whether you installed
@waniwani/chat, and whether you removed@waniwani/sdkor@ai-sdk/mcp.
Common mistakes
- Installing
@waniwani/chatand keeping the old import path. 1.0 has no@waniwani/sdk/chatentry. The build fails until every import names@waniwani/chat. - Keeping
chat/in adistpath. The embed sits at@waniwani/chat/dist/embed.js, not@waniwani/chat/dist/chat/embed.js. - Copying the forwarder. A copy step that still reads
@waniwani/sdk/dist/chat/embed.jsnow copies a 600-byte forwarder, which loads the chat from jsDelivr. A page whose Content Security Policy blockscdn.jsdelivr.netthen shows no chat. Copy@waniwani/chat/dist/embed.js. - Leaving script tags on the old CDN path. They keep working through the forwarder in every 1.x release, and 2.0.0 removes it. Move them to the dashboard snippet now.
- Moving an
init()tag to the loader.app.waniwani.ai/embed.jsadds the chat's script tag at run time, and that script can run afterDOMContentLoaded. A page that callswindow.WaniWani.chat.init()onDOMContentLoadedthen finds nowindow.WaniWani. Load@waniwani/chat@1straight from jsDelivr for a tag withoutdata-token. - Pinning the embed to a CDN version. A pinned
cdn.jsdelivr.netURL never gets fixes. The dashboard snippet loads the current release throughapp.waniwani.ai/embed.js. - Removing
@waniwani/sdkwhile server code still imports it. Flows, tracking,withWaniwanianduseWaniwanistay in@waniwani/sdk. Remove it only when step 5 finds no import left. - Skipping the verify step. A clean
bun run typecheckplus greenbun testis the definition of done, and a web app also needs a green build.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

