diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index 66b09ea07..81d9ecb73 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -8,11 +8,11 @@ on:
- closed
jobs:
- publish:
+ publish-packages:
if: github.event.pull_request.merged == true && startsWith(github.event.pull_request.head.ref, 'release/')
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v4
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
- name: Extract version from branch name
run: |
@@ -20,6 +20,7 @@ jobs:
VERSION="${BRANCH#release/}"
echo "BRANCH=$BRANCH" >> $GITHUB_ENV
echo "VERSION_TAG=v$VERSION" >> $GITHUB_ENV
+
- name: Mark as Latest Release in GitHub Releases
env:
GH_TOKEN: '${{ secrets.GITHUB_TOKEN }}'
@@ -31,15 +32,82 @@ jobs:
with:
node_version_file: '.nvmrc'
- - run: pnpm build
+ - run: pnpm build:packages
+
- run: pnpm publish:packages
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
- - name: Deploy Docs to Juno satellite
- uses: junobuild/juno-action@main
+ publish-docs:
+ needs: publish-packages
+ runs-on: ubuntu-latest
+ steps:
+ - name: Create GitHub App Token
+ uses: actions/create-github-app-token@df432ceedc7162793a195dd1713ff69aefc7379e # v2.0.6
+ id: generate_token
with:
- args: deploy --mode production --immediate
+ app-id: ${{ vars.PR_AUTOMATION_BOT_PUBLIC_APP_ID }}
+ private-key: ${{ secrets.PR_AUTOMATION_BOT_PUBLIC_PRIVATE_KEY }}
+ owner: ${{ github.repository_owner }}
+ repositories: icp-js-sdk-docs
+
+ - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+ - name: Setup PNPM
+ uses: dfinity/ci-tools/actions/setup-pnpm@main
+ with:
+ node_version_file: '.nvmrc'
+
+ - uses: dfinity/ci-tools/actions/extract-version@main
+ id: extract-version
+ with:
+ file: 'package.json'
+
+ - name: Prepare version
+ id: ver
+ run: |
+ echo "major_minor_version=v${{ steps.extract-version.outputs.major }}.${{ steps.extract-version.outputs.minor }}" >> $GITHUB_OUTPUT
+ echo "major_minor_patch_version=v${{ steps.extract-version.outputs.major }}.${{ steps.extract-version.outputs.minor }}.${{ steps.extract-version.outputs.patch }}" >> $GITHUB_OUTPUT
+
+ - name: Build docs for version ${{ steps.ver.outputs.major_minor_version }}
+ working-directory: docs
+ env:
+ DOCS_VERSION: ${{ steps.ver.outputs.major_minor_version }}
+ DOCS_VERSIONS_DROPDOWN_TITLE_VERSION: ${{ steps.ver.outputs.major_minor_patch_version }}
+ run: pnpm build --outDir dist/${{ steps.ver.outputs.major_minor_version }}
+
+ - name: Build docs for version latest
+ working-directory: docs
env:
- JUNO_TOKEN: ${{ secrets.JUNO_TOKEN }}
- PROJECT_PATH: docs
+ DOCS_VERSION: latest
+ DOCS_VERSIONS_DROPDOWN_TITLE_VERSION: ${{ steps.ver.outputs.major_minor_patch_version }}
+ run: pnpm build --outDir dist/latest
+
+ - name: Checkout icp-pages branch
+ uses: actions/checkout@v4
+ with:
+ ref: icp-pages
+ path: icp-pages
+
+ - name: Assemble docs
+ uses: dfinity/ci-tools/actions/assemble-docs@main
+ with:
+ assets_dir: 'docs/dist/${{ steps.ver.outputs.major_minor_version }}'
+ version: ${{ steps.ver.outputs.major_minor_version }}
+ target_dir: 'icp-pages'
+ version_label: ${{ steps.ver.outputs.major_minor_version }}
+
+ - name: Assemble docs
+ uses: dfinity/ci-tools/actions/assemble-docs@main
+ with:
+ assets_dir: 'docs/dist/latest'
+ version: 'latest'
+ target_dir: 'icp-pages'
+ version_label: 'Latest (${{ steps.ver.outputs.major_minor_patch_version }})'
+
+ - name: Submit Documentation
+ uses: dfinity/ci-tools/actions/submit-docs@main
+ with:
+ destination_repo: 'dfinity/icp-js-sdk-docs'
+ token: ${{ steps.generate_token.outputs.token }}
+ target_dir: 'icp-pages'
diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
index 9ddd06b57..845fd7b2c 100644
--- a/docs/astro.config.mjs
+++ b/docs/astro.config.mjs
@@ -5,11 +5,18 @@ import { additionalFilesPlugin } from '@dfinity/starlight/additional-files';
import { markdownUrlsPlugin } from '@dfinity/starlight/markdown-urls';
import { dfinityStarlightTheme } from '@dfinity/starlight/theme';
import { libsPlugin } from '@dfinity/starlight/libs';
+import { versionedSidebarPlugin } from '@dfinity/starlight/versioned-sidebar';
+
+const BASE_DOCS_PATH = '/core';
+const docsVersion = process.env.DOCS_VERSION ?? 'local';
+
+const UPGRADE_BANNER_CONTENT =
+ 'Still using @dfinity/agent? Migrate to @icp-sdk/core!';
// https://astro.build/config
export default defineConfig({
site: 'https://js.icp.build/',
- base: '/core/',
+ base: `${BASE_DOCS_PATH}/${docsVersion}/`,
image: {
service: passthroughImageService(),
},
@@ -26,7 +33,14 @@ export default defineConfig({
typeDoc: {
exclude: ['../packages/core', '../packages/migrate'],
},
- frontmatter: { editUrl: false, next: true, prev: true },
+ frontmatter: {
+ editUrl: false,
+ next: true,
+ prev: true,
+ banner: {
+ content: UPGRADE_BANNER_CONTENT,
+ },
+ },
}),
additionalFilesPlugin({
additionalFiles: [
@@ -38,10 +52,16 @@ export default defineConfig({
editUrl: false,
next: false,
prev: false,
+ banner: {
+ content: UPGRADE_BANNER_CONTENT,
+ },
},
},
],
}),
+ versionedSidebarPlugin({
+ versionsJsonPath: `${BASE_DOCS_PATH}/versions.json`,
+ }),
],
sidebar: [
{
diff --git a/docs/plugins/package.json b/docs/plugins/package.json
index a0bdbbca9..529d19781 100644
--- a/docs/plugins/package.json
+++ b/docs/plugins/package.json
@@ -43,6 +43,9 @@
"./additional-files": "./src/additional-files.ts",
"./libs": "./src/libs.ts",
"./markdown-urls": "./src/markdown-urls.ts",
- "./theme": "./src/theme.ts"
+ "./theme": "./src/theme.ts",
+ "./versioned-sidebar": "./src/versioned-sidebar/index.ts",
+ "./versioned-sidebar/components/VersionedSidebar.astro": "./src/versioned-sidebar/components/VersionedSidebar.astro",
+ "./versioned-sidebar/components/VersionDropdown.astro": "./src/versioned-sidebar/components/VersionDropdown.astro"
}
}
diff --git a/docs/plugins/src/versioned-sidebar/components/VersionDropdown.astro b/docs/plugins/src/versioned-sidebar/components/VersionDropdown.astro
new file mode 100644
index 000000000..f10554ffa
--- /dev/null
+++ b/docs/plugins/src/versioned-sidebar/components/VersionDropdown.astro
@@ -0,0 +1,100 @@
+---
+const IS_DEV = import.meta.env.DEV;
+const BASE_URL = import.meta.env.BASE_URL;
+const DOCS_VERSIONS_DROPDOWN_TITLE_VERSION = import.meta.env.DOCS_VERSIONS_DROPDOWN_TITLE_VERSION;
+---
+
+
@dfinity/agent? Migrate to @icp-sdk/core!
---
This release marks a major update to the ICP JavaScript SDK, introducing several breaking changes, new features, and improvements. This guide is intended to help developers upgrade their projects to the latest version. Among the key improvements, this release eliminates Buffer and similar dependencies, significantly [reducing bundle size](#bundle-size) and improving performance across all packages.
diff --git a/docs/src/content/docs/upgrading/v4.md b/docs/src/content/docs/upgrading/v4.md
deleted file mode 100644
index e3a90136d..000000000
--- a/docs/src/content/docs/upgrading/v4.md
+++ /dev/null
@@ -1,114 +0,0 @@
----
-title: Upgrading to @icp-sdk/core
-description: Upgrading guide for the new @icp-sdk/core package
-next:
- label: Overview
- link: /core/latest/
----
-
-The new `@icp-sdk/core` package is made up of multiple submodules, each of which contains the functionality of the respective old `@dfinity/...` package.
-
-## Automatic
-
-We provide a CLI tool to automatically upgrade your code to use the new package.
-
-Simply run the following command in the root of your project:
-
-```shell
-npx @icp-sdk/core-migrate@latest
-```
-
-For more migration options, run `npx @icp-sdk/core-migrate@latest --help`.
-
-## Manual
-
-Everything previously exported from the individual `@dfinity/*` packages is now
-exported from a `@icp-sdk/core/*` submodule.
-
-1. Remove the following packages, if present:
- - `@dfinity/agent`
- - `@dfinity/candid`
- - `@dfinity/identity`
- - `@dfinity/identity-secp256k1`
- - `@dfinity/principal`
-
- E.g.
-
- ```shell
- npm remove @dfinity/{agent,candid,identity,identity-secp256k1,principal}
- ```
-
-2. Install the new `@icp-sdk/core` package:
-
- ```shell
- npm i @icp-sdk/core
- ```
-
-3. Replace old imports with new imports, if present:
-
- | Old Import | New Import |
- | ----------------------------- | ---------------------------------- |
- | `@dfinity/agent` | `@icp-sdk/core/agent` |
- | `@dfinity/candid` | `@icp-sdk/core/candid` |
- | `@dfinity/identity` | `@icp-sdk/core/identity` |
- | `@dfinity/identity-secp256k1` | `@icp-sdk/core/identity/secp256k1` |
- | `@dfinity/principal` | `@icp-sdk/core/principal` |
-
- E.g.
-
- ```ts
- - import { HttpAgent } from '@dfinity/agent';
- + import { HttpAgent } from '@icp-sdk/core/agent';
- ```
-
-## FAQ
-
-### TypeScript `moduleResolution`
-
-If you're using TypeScript, you need to set the [`moduleResolution`](https://www.typescriptlang.org/tsconfig/#moduleResolution) to either `node16`, `nodenext` or `bundler` in your `tsconfig.json` file.
-
-```json
-{
- "compilerOptions": {
- "moduleResolution": "node16"
- }
-}
-```
-
-### Using agent-js v2
-
-If you're using agent-js v2, you need to upgrade to v3 before upgrading to `@icp-sdk/core`. You can find the release notes [here](https://js.icp.build/core/release-notes/v300/).
-
-### Workspaces
-
-If you're using a workspace, you must run the migration tool for each package in the workspace that has any `@dfinity/*` dependencies. You may need to first uninstall the `@dfinity/*` packages manually from all the packages in the workspace before running the migration tool, to avoid version conflicts.
-
-A similar approach can be used for monorepos.
-
-### Tree-shaking
-
-Tree-shaking is supported, so you can import only the submodules you need and your bundler will automatically remove the unused code.
-
-### Using `@dfinity/*` packages in other places than imports
-
-The `@icp-sdk/core-migrate` CLI tool only replaces the `@dfinity/*` occurrences in imports. If you are using `@dfinity/*` packages somewhere else in your code, e.g. in tests mocks, you will need to find and replace the occurrences **manually**.
-
-E.g.
-
-```diff
-- vi.mock('@dfinity/agent', () => ({
-+ vi.mock('@icp-sdk/core/agent', () => ({
- ...
-}));
-```
-
-### `@dfinity/assets` and `@dfinity/auth-client`
-
-The `@dfinity/assets` and `@dfinity/auth-client` packages are not included in `@icp-sdk/core`. They will be included in other `@icp-sdk/*` packages in the near future. For now, you can still use them.
-
-### `@dfinity/use-auth-client`
-
-The `@dfinity/use-auth-client` package is not included in `@icp-sdk/core` and **will be deprecated soon**. Please consider using other libraries instead. Recommended alternatives:
-
-- [ic-use-internet-identity](https://www.npmjs.com/package/ic-use-internet-identity)
-- [@ic-reactor/react](https://www.npmjs.com/package/@ic-reactor/react)
diff --git a/docs/src/pages/index.astro b/docs/src/pages/index.astro
index 7242adb2d..de72669c5 100644
--- a/docs/src/pages/index.astro
+++ b/docs/src/pages/index.astro
@@ -26,7 +26,7 @@ import icpSvg from '@dfinity/starlight/assets/icp.svg';
}}
>
@icp-sdk/core/agent docs
+ See @dfinity/agent docs
+ @dfinity/assets docs
+ @dfinity/auth-client docs
@icp-sdk/core/candid docs
+ See @dfinity/candid docs
@icp-sdk/core/identity docs
+ See @dfinity/identity docs
+ @dfinity/identity-secp256k1 docs
@icp-sdk/core/principal docs
+ See @dfinity/principal docs
+ @dfinity/use-auth-client docs
- If you're using @dfinity/agent version 3.x, you can migrate to
- @icp-sdk/core with the help of our automated migration tools or manual migration
- guide.
-
@icp-sdk/core
-
If you're still using @dfinity/agent version 2.x, you can migrate to 3.x with
the help of our migration guide.