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; +--- + +
+ + +
+ + + + diff --git a/docs/plugins/src/versioned-sidebar/components/VersionedSidebar.astro b/docs/plugins/src/versioned-sidebar/components/VersionedSidebar.astro new file mode 100644 index 000000000..c5ac19773 --- /dev/null +++ b/docs/plugins/src/versioned-sidebar/components/VersionedSidebar.astro @@ -0,0 +1,18 @@ +--- +import MobileMenuFooter from '@astrojs/starlight/components/MobileMenuFooter.astro'; +import SidebarPersister from '@astrojs/starlight/components/SidebarPersister.astro'; +import SidebarSublist from '@astrojs/starlight/components/SidebarSublist.astro'; +import VersionDropdown from './VersionDropdown.astro'; + +const { sidebar } = Astro.locals.starlightRoute; +--- + + + + + + + +
+ +
diff --git a/docs/plugins/src/versioned-sidebar/index.ts b/docs/plugins/src/versioned-sidebar/index.ts new file mode 100644 index 000000000..a0050a82f --- /dev/null +++ b/docs/plugins/src/versioned-sidebar/index.ts @@ -0,0 +1,55 @@ +import type { StarlightPlugin } from '@astrojs/starlight/types'; + +/** + * Options for the VersionsPlugin. + */ +interface VersionedSidebarPluginOptions { + /** + * The path at which the `versions.json` file is served in production. + */ + versionsJsonPath: string; +} + +/** + * You can set the `DOCS_VERSIONS_DROPDOWN_TITLE_VERSION` environment variable to show a version above the versions dropdown. + * + * @example + * ```bash + * DOCS_VERSIONS_DROPDOWN_TITLE_VERSION=v3.2.1 pnpm build + * ``` + * + * This will result in: + * ```html + *
+ * + * + *
+ * ``` + */ +export function versionedSidebarPlugin(opts: VersionedSidebarPluginOptions): StarlightPlugin { + return { + name: 'versions-starlight-plugin', + hooks: { + 'config:setup': ctx => { + ctx.updateConfig({ + head: [ + ...(ctx.config.head ?? []), + { + tag: 'meta', + attrs: { + name: 'versions-json-path', + content: opts.versionsJsonPath, + }, + }, + ], + components: { + ...ctx.config.components, + Sidebar: '@dfinity/starlight/versioned-sidebar/components/VersionedSidebar.astro', + }, + }); + }, + }, + }; +} diff --git a/docs/plugins/tsconfig.json b/docs/plugins/tsconfig.json index fbc2f5fc1..9851a4db0 100644 --- a/docs/plugins/tsconfig.json +++ b/docs/plugins/tsconfig.json @@ -1,3 +1,6 @@ { - "extends": "astro/tsconfigs/strictest" + "extends": "astro/tsconfigs/strictest", + "compilerOptions": { + "types": ["@astrojs/starlight/locals"] + } } diff --git a/docs/src/content/docs/upgrading/v3.md b/docs/src/content/docs/upgrading/v3.md index a5c5847ef..6dcf33bfb 100644 --- a/docs/src/content/docs/upgrading/v3.md +++ b/docs/src/content/docs/upgrading/v3.md @@ -1,6 +1,11 @@ --- -title: Release notes for v3.0.0 -description: Release notes for the ICP JavaScript SDK v3.0.0. +title: Upgrading to v3 +description: Upgrade your project to the v3 of the ICP JavaScript SDK. +sidebar: + label: v3 + order: 2 +banner: + content: Still using @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'; }} >
-

Modules

+

Libraries

@@ -34,31 +34,52 @@ import icpSvg from '@dfinity/starlight/assets/icp.svg'; other JavaScript runtimes. - See @icp-sdk/core/agent docs + See @dfinity/agent docs + + + + + Manage assets on an Internet Computer assets canister. + + + See @dfinity/assets docs + + + + + Simple interface to get your web application authenticated with the Internet Identity Service. + + + See @dfinity/auth-client docs - Build applications that interact with the Internet Computer from browsers, Node.js, and - other JavaScript runtimes. + JavaScript and TypeScript library to work with Candid interfaces. - See @icp-sdk/core/candid docs + See @dfinity/candid docs - Build applications that interact with the Internet Computer from browsers, Node.js, and - other JavaScript runtimes. + JavaScript and TypeScript library to manage Identities and enable simple Web Authentication flows. - See @icp-sdk/core/identity docs + See @dfinity/identity docs + + + + + The `Secp256k1KeyIdentity` package provides an implementation of the `SignIdentity` interface for the `secp256k1` elliptic curve. + + + See @dfinity/identity-secp256k1 docs - Build applications that interact with the Internet Computer from browsers, Node.js, and - other JavaScript runtimes. + JavaScript and TypeScript library to work with Internet Computer Principals. - See @icp-sdk/core/principal docs + See @dfinity/principal docs + + + + + A package for Internet Computer React developers, making it easier to integrate the auth-client with your React application. + + + See @dfinity/use-auth-client docs @@ -75,25 +104,7 @@ import icpSvg from '@dfinity/starlight/assets/icp.svg';

Upgrading

- - -

- 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. -

- - - Migrate to @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.