docs: add library development guides (#1128)

* docs: add library development guides

* docs: update installation guide

---------

Co-authored-by: Nathan Mc Grath <contact@nathanos.dev>

Author: ilbertt

docs/astro.config.mjs

@@ -52,6 +52,7 @@ export default defineConfig({
                 { label: 'Installation', link: '/installation' },
                 { label: 'Quick Start', link: '/quick-start' },
                 { label: 'Typescript', link: '/typescript' },
+                { label: 'Library Development', link: '/library-development' },
               ],
             },
           ],

docs/src/content/docs/installation.mdx

@@ -22,6 +22,12 @@ The `@icp-sdk/core` is a single, unified package that contains all the modules y
   </TabItem>
 </Tabs>
 
+> If you're using pnpm, you might need to install the peer dependencies of `@icp-sdk/core` manually:
+>
+> ```shell
+> pnpm install @dfinity/agent @dfinity/candid @dfinity/identity @dfinity/identity-secp256k1 @dfinity/principal
+> ```
+
 ## CDN
 
 We do not recommend using the CDN distribution of the `@icp-sdk/core` package for **production** applications.

docs/src/content/docs/library-development.mdx

@@ -0,0 +1,44 @@
+---
+title: Library Development
+description: Guide for building libraries that depend on @icp-sdk/core
+sidebar:
+  order: 4
+---
+
+If you're building a library that depends on `@icp-sdk/core`, there are some specific considerations to ensure your library works correctly with bundlers and provides the best experience for your users.
+
+## Bundler Configuration
+
+### Rollup/Vite
+
+When using Rollup or Vite (which uses Rollup under the hood), you need to specify each `@icp-sdk/core` submodule as an external dependency:
+
+```js
+// rollup.config.js or vite.config.js
+export default {
+  build: {
+    rollupOptions: {
+      external: [
+        '@icp-sdk/core/agent',
+        '@icp-sdk/core/candid',
+        '@icp-sdk/core/identity',
+        '@icp-sdk/core/identity/secp256k1',
+        '@icp-sdk/core/principal',
+      ],
+      output: {
+        globals: {
+          '@icp-sdk/core/agent': 'icp-sdk-core-agent',
+          '@icp-sdk/core/candid': 'icp-sdk-core-candid',
+          '@icp-sdk/core/identity': 'icp-sdk-core-identity',
+          '@icp-sdk/core/identity/secp256k1': 'icp-sdk-core-identity-secp256k1',
+          '@icp-sdk/core/principal': 'icp-sdk-core-principal',
+        },
+      },
+    },
+  },
+};
+```
+
+## TypeScript Configuration
+
+If your library is written in TypeScript, make sure your `tsconfig.json` uses compatible module resolution. See the [Typescript](./typescript.mdx) documentation for more details.

docs/src/content/docs/upgrading/v4.md

@@ -64,7 +64,7 @@ exported from a `@icp-sdk/core/*` submodule.
    + import { HttpAgent } from '@icp-sdk/core/agent';
    ```
 
-## FAQ
+## Troubleshooting
 
 ### TypeScript `moduleResolution`
 
@@ -115,3 +115,36 @@ The `@dfinity/use-auth-client` package is not included in `@icp-sdk/core` and **
 
 - [ic-use-internet-identity](https://www.npmjs.com/package/ic-use-internet-identity)
 - [@ic-reactor/react](https://www.npmjs.com/package/@ic-reactor/react)
+
+### Installing with pnpm
+
+If you're using pnpm, you might need to install the peer dependencies of `@icp-sdk/core` manually:
+
+```shell
+pnpm install @dfinity/agent @dfinity/candid @dfinity/identity @dfinity/identity-secp256k1 @dfinity/principal
+```
+
+### Building libraries with Rollup/Vite
+
+If you're building a library that depends on `@icp-sdk/core`, you need to specify each submodule you're using in your Rollup configuration (this also applies to Vite, which uses Rollup under the hood):
+
+```js
+rollupOptions: {
+  external: [
+    '@icp-sdk/core/agent',
+    '@icp-sdk/core/candid',
+    '@icp-sdk/core/identity',
+    '@icp-sdk/core/identity/secp256k1',
+    '@icp-sdk/core/principal',
+  ],
+  output: {
+    globals: {
+      '@icp-sdk/core/agent': 'icp-sdk-core-agent',
+      '@icp-sdk/core/candid': 'icp-sdk-core-candid',
+      '@icp-sdk/core/identity': 'icp-sdk-core-identity',
+      '@icp-sdk/core/identity/secp256k1': 'icp-sdk-core-identity-secp256k1',
+      '@icp-sdk/core/principal': 'icp-sdk-core-principal',
+    },
+  },
+},
+```