feat: docs - typescript references (#1203)

.gitignore

@@ -1,16 +1,15 @@
-node_modules/
-
+.DS_Store
+.aider*
+.astro/
 .idea/
-dist/
 build/
 cache/
-*.tsbuildinfo
-
-.env
-*.mjs
-!*.config.mjs
 coverage/
-.DS_Store
+dist/
+node_modules/
+references/
+
 *.log
+*.tsbuildinfo
+.env
 .npmrc
-.aider*

.vscode/extensions.json

@@ -1,5 +1,6 @@
 {
   "recommendations": [
+    "astro-build.astro-vscode",
     "antfu.file-nesting",
     "biomejs.biome",
     "bradlc.vscode-tailwindcss",

.vscode/launch.json

@@ -0,0 +1,11 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "command": "bun --cwd ./docs dev",
+      "name": "Docs dev",
+      "request": "launch",
+      "type": "node-terminal"
+    }
+  ]
+}

docs/astro.config.mjs

@@ -0,0 +1,130 @@
+import react from "@astrojs/react";
+import starlight from "@astrojs/starlight";
+import { rendererRich, transformerTwoslash } from "@shikijs/twoslash";
+import { defineConfig } from "astro/config";
+import { createStarlightTypeDocPlugin } from "starlight-typedoc";
+
+function createTypeDoc(docs, nest = "") {
+  const generatedDocs = docs.reduce(
+    (acc, { label, entrypoint }) => {
+      const [typeDoc, sidebarGroup] = createStarlightTypeDocPlugin();
+      acc.plugins.push(
+        typeDoc({
+          sidebar: { label, collapsed: true },
+          entryPoints: [`../packages/${entrypoint}`],
+          output: `references${nest}${label}`,
+        }),
+      );
+      acc.items.push(sidebarGroup);
+
+      return acc;
+    },
+    { plugins: [], items: [] },
+  );
+
+  return nest
+    ? {
+        plugins: generatedDocs.plugins,
+        items: [{ collapsed: true, label: nest, items: generatedDocs.items }],
+      }
+    : generatedDocs;
+}
+
+function createDocs() {
+  /**
+   * I recommend commenting out unnecessary entries in development as re-generating the docs is a bit slow.
+   */
+
+  const base = createTypeDoc([
+    { label: "/core", entrypoint: "core/src/index.ts" },
+    { label: "/helpers", entrypoint: "helpers/src/index.ts" },
+    { label: "/helpers/api", entrypoint: "helpers/src/api/index.ts" },
+  ]);
+
+  const plugins = createTypeDoc(
+    [
+      { label: "/chainflip", entrypoint: "plugins/src/chainflip/index.ts" },
+      { label: "/evm", entrypoint: "plugins/src/evm/index.ts" },
+      { label: "/kado", entrypoint: "plugins/src/kado/index.ts" },
+      { label: "/radix", entrypoint: "plugins/src/radix/index.ts" },
+      { label: "/thorchain", entrypoint: "plugins/src/thorchain/index.ts" },
+    ],
+    "/plugins",
+  );
+
+  const toolboxes = createTypeDoc(
+    [
+      { label: "/cosmos", entrypoint: "toolboxes/src/cosmos/index.ts" },
+      { label: "/evm", entrypoint: "toolboxes/src/evm/index.ts" },
+      { label: "/radix", entrypoint: "toolboxes/src/radix/index.ts" },
+      { label: "/solana", entrypoint: "toolboxes/src/solana/index.ts" },
+      { label: "/substrate", entrypoint: "toolboxes/src/substrate/index.ts" },
+      { label: "/utxo", entrypoint: "toolboxes/src/utxo/index.ts" },
+    ],
+    "/toolboxes",
+  );
+
+  const wallets = createTypeDoc(
+    [
+      { label: "/bitget", entrypoint: "wallets/src/bitget/index.ts" },
+      { label: "/coinbase", entrypoint: "wallets/src/coinbase/index.ts" },
+      { label: "/ctrl", entrypoint: "wallets/src/ctrl/index.ts" },
+      { label: "/evm-extensions", entrypoint: "wallets/src/evm-extensions/index.ts" },
+      { label: "/exodus", entrypoint: "wallets/src/exodus/index.ts" },
+      { label: "/keepkey", entrypoint: "wallets/src/keepkey/index.ts" },
+      { label: "/keepkey-bex", entrypoint: "wallets/src/keepkey-bex/index.ts" },
+      { label: "/keplr", entrypoint: "wallets/src/keplr/index.ts" },
+      { label: "/keystore", entrypoint: "wallets/src/keystore/index.ts" },
+      { label: "/ledger", entrypoint: "wallets/src/ledger/index.ts" },
+      { label: "/okx", entrypoint: "wallets/src/okx/index.ts" },
+      { label: "/phantom", entrypoint: "wallets/src/phantom/index.ts" },
+      { label: "/polkadotjs", entrypoint: "wallets/src/polkadotjs/index.ts" },
+      { label: "/radix", entrypoint: "wallets/src/radix/index.ts" },
+      { label: "/talisman", entrypoint: "wallets/src/talisman/index.ts" },
+      { label: "/trezor", entrypoint: "wallets/src/trezor/index.ts" },
+      { label: "/walletconnect", entrypoint: "wallets/src/walletconnect/index.ts" },
+    ],
+    "/wallets",
+  );
+
+  return {
+    plugins: [...base.plugins, ...plugins.plugins, ...toolboxes.plugins, ...wallets.plugins],
+    sidebarItems: [...base.items, ...plugins.items, ...toolboxes.items, ...wallets.items],
+  };
+}
+
+const { plugins: docsPlugins, sidebarItems: docsSidebarItems } = createDocs();
+
+// https://astro.build/config
+export default defineConfig({
+  markdown: {
+    syntaxHighlight: "shiki",
+    shikiConfig: {
+      wrap: true,
+      theme: "github-dark",
+      transformers: [transformerTwoslash({ renderer: rendererRich() })],
+    },
+  },
+  integrations: [
+    react(),
+    starlight({
+      expressiveCode: false,
+      title: "SwapKit Docs",
+      customCss: ["./src/styles/global.css", "@shikijs/twoslash/style-rich.css"],
+      social: {
+        github: "https://github.com/thorswap/swapkit",
+        "x.com": "https://x.com/SwapKitPowered",
+      },
+      plugins: [...docsPlugins],
+      sidebar: [
+        { label: "Guides", autogenerate: { directory: "guides" } },
+        { label: "Others", autogenerate: { directory: "others" } },
+        {
+          label: "References",
+          collapsed: true,
+          items: [{ label: "@swapkit", items: docsSidebarItems }],
+        },
+      ],
+    }),
+  ],
+});

docs/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@internal/docs",
+  "type": "module",
+  "version": "0.0.0",
+  "scripts": {
+    "dev": "astro dev",
+    "start": "astro dev",
+    "build": "astro build",
+    "preview": "astro preview",
+    "astro": "astro"
+  },
+  "dependencies": {
+    "@astrojs/react": "4.2.0",
+    "@astrojs/starlight": "0.32.1",
+    "@shikijs/twoslash": "3.0.0",
+    "@swapkit/core": "workspace:*",
+    "@swapkit/helpers": "workspace:*",
+    "@swapkit/plugins": "workspace:*",
+    "@swapkit/sdk": "workspace:*",
+    "@swapkit/toolboxes": "workspace:*",
+    "@swapkit/wallets": "workspace:*",
+    "astro": "5.3.0",
+    "expressive-code-twoslash": "0.4.0",
+    "sharp": "0.33.5",
+    "starlight-typedoc": "0.19.0",
+    "typedoc": "0.27.7",
+    "typedoc-plugin-markdown": "4.4.2"
+  }
+}

docs/src/content.config.ts

@@ -0,0 +1,7 @@
+import { defineCollection } from "astro:content";
+import { docsLoader } from "@astrojs/starlight/loaders";
+import { docsSchema } from "@astrojs/starlight/schema";
+
+export const collections = {
+  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
+};

docs/src/content/docs/guides/example.md

@@ -0,0 +1,11 @@
+---
+title: Example Guide
+description: A guide in my new Starlight docs site.
+---
+
+Guides lead a user through a specific task they want to accomplish, often with a sequence of steps.
+Writing a good guide requires thinking about what your users are trying to do.
+
+## Further reading
+
+- Read [about how-to guides](https://diataxis.fr/how-to-guides/) in the Diátaxis framework

docs/src/content/docs/index.mdx

@@ -0,0 +1,36 @@
+---
+title: Welcome to Starlight
+description: Get started building your docs site with Starlight.
+template: splash
+hero:
+  tagline: Congrats on setting up a new Starlight project!
+  image:
+    file: ../../assets/houston.webp
+  actions:
+    - text: Example Guide
+      link: /guides/example/
+      icon: right-arrow
+    - text: Read the Starlight docs
+      link: https://starlight.astro.build
+      icon: external
+      variant: minimal
+---
+
+import { Card, CardGrid } from "@astrojs/starlight/components";
+
+## Next steps
+
+<CardGrid stagger>
+	<Card title="Update content" icon="pencil">
+		Edit `src/content/docs/index.mdx` to see this page change.
+	</Card>
+	<Card title="Add new content" icon="add-document">
+		Add Markdown or MDX files to `src/content/docs` to create new pages.
+	</Card>
+	<Card title="Configure your site" icon="setting">
+		Edit your `sidebar` and other config in `astro.config.mjs`.
+	</Card>
+	<Card title="Read the docs" icon="open-book">
+		Learn more in [the Starlight Docs](https://starlight.astro.build/).
+	</Card>
+</CardGrid>

docs/src/content/docs/others/example.md

@@ -0,0 +1,11 @@
+---
+title: Example Reference
+description: A reference page in my new Starlight docs site.
+---
+
+Reference pages are ideal for outlining how things work in terse and clear terms.
+Less concerned with telling a story or addressing a specific use case, they should give a comprehensive outline of what you're documenting.
+
+## Further reading
+
+- Read [about reference](https://diataxis.fr/reference/) in the Diátaxis framework

docs/MIGRATE_CORE_v4.md → docs/src/content/docs/others/migrate_to_v4.mdx

@@ -1,4 +1,25 @@
-# MIGRATE FROM CORE v3 to v4
+---
+title: Migrate to v4
+description: A guide to migrate to v4 and update your codebase.
+---
+
+```ts twoslash
+import { EVMToolbox } from "@swapkit/toolboxes/evm"
+
+const evm = EVMToolbox
+
+
+
+
+
+
+
+
+
+
+
+```
+
 
 > [!IMPORTANT]Read before continue
 > We migrated to combined functionality packages to simplify developer experience. You will have to change imports to use the new version of the packages.
@@ -115,4 +136,4 @@ Methods were scoped under `SwapKitApi` object and split into related api endpoin
 #### @swapkit/helpers
 
 - `ensureEVMApiKeys` -> removed
-- `setRequestClientConfig` -> removed - use `SKConfig` directly
+- `setRequestClientConfig` -> removed - use `SKConfig` directly -->

docs/src/styles/global.css

@@ -0,0 +1,9 @@
+@media (prefers-color-scheme: dark) {
+  :root {
+    --twoslash-popup-bg: color-mix(in srgb, var(--astro-code-background) 80%, black) !important;
+  }
+}
+
+.sidebar-pane {
+  width: 360px !important;
+}

docs/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": ["../node_modules/astro/tsconfigs/base.json", "../tools/typescript/base.json"],
+  "compilerOptions": {
+    "types": ["bun-types"]
+  },
+  "exclude": ["node_modules", "dist"],
+  "include": [".astro/types.d.ts", "./src", "../packages/**/*"]
+}

package.json

@@ -7,7 +7,7 @@
   "devDependencies": {
     "@biomejs/biome": "1.9.4",
     "@changesets/changelog-github": "0.5.1",
-    "@changesets/cli": "2.28.0",
+    "@changesets/cli": "2.28.1",
     "@types/node": "22.13.4",
     "@types/react": "19.0.10",
     "@types/react-dom": "19.0.4",
@@ -26,6 +26,7 @@
     "build:ci": "bun --filter '*' build",
     "build:debug": "DEBUG=true bun --filter '*' build",
     "clean": "bun --filter '*' clean && rm -rf node_modules; bun install",
+    "docs": "bun --cwd ./docs",
     "deps": "bun ncu --root -u -i -ws",
     "generate:tokens": "bun --filter '@swapkit/helpers' build; bun --cwd packages/helpers generate-tokens; bun lint",
     "lint": "bun --filter '*' --elide-lines=0 lint",
@@ -56,5 +57,5 @@
     "tiny-secp256k1",
     "usb"
   ],
-  "workspaces": ["packages/*", "playgrounds/*", "tools/*"]
+  "workspaces": ["packages/*", "playgrounds/*", "tools/*", "docs"]
 }

packages/sdk/src/index.ts

@@ -18,7 +18,7 @@ export const defaultPlugins = {
   ...RadixPlugin,
 };
 
-export function createSwapKit(config: Parameters<typeof SwapKit>[0]) {
+export function createSwapKit(config: Parameters<typeof SwapKit>[0] = {}) {
   return SwapKit({
     ...config,
     wallets: defaultWallets,

packages/wallets/package.json

@@ -7,7 +7,7 @@
     "@cosmjs/crypto": "0.33.0",
     "@cosmjs/proto-signing": "0.33.0",
     "@keepkey/keepkey-sdk": "0.2.62",
-    "@keplr-wallet/types": "0.12.189",
+    "@keplr-wallet/types": "0.12.190",
     "@ledgerhq/devices": "8.4.4",
     "@ledgerhq/errors": "6.19.1",
     "@ledgerhq/hw-app-btc": "10.5.0",

playgrounds/nextjs/package.json

@@ -47,7 +47,7 @@
     "react": "19.0.0",
     "react-dom": "19.0.0",
     "react-hook-form": "7.54.2",
-    "sonner": "2.0.0",
+    "sonner": "2.0.1",
     "stream-browserify": "3.0.0",
     "stream-http": "3.2.0",
     "tailwind-merge": "3.0.1",