diff --git a/website/docs/01-run-lumos-in-the-browser.md b/website/docs/01-run-lumos-in-the-browser.md index f2fd7f8ae..8cccd4ca5 100644 --- a/website/docs/01-run-lumos-in-the-browser.md +++ b/website/docs/01-run-lumos-in-the-browser.md @@ -10,8 +10,6 @@ sidebar_position: 2 Lumos was originally run on NodeJS only. To run on browser, we replaced native indexer with ckb-indexer, added BI which is a big number library, and a series of other upgrades. -Also, we need polyfill the NodeJS API(such as `crypto`), and change your build toolchain config to support. - The following example of getting the balance will show you how to use lumos in your web project. ```shell diff --git a/website/docs/migrations/migrate-to-v0.20.md b/website/docs/migrations/migrate-to-v0.20.md index 06523a1c3..2a7cc36e7 100644 --- a/website/docs/migrations/migrate-to-v0.20.md +++ b/website/docs/migrations/migrate-to-v0.20.md @@ -1,10 +1,5 @@ # Migration to Lumos 0.20 -## Browser shiming - -If you are using Lumos in the browser, please add configuration according to -this [doc](../recipes/cra-vite-webpack-or-other) - ## Remove `computeScriptHash` Second Parameter In an early version, we make the second parameter be ignored in it's implement. diff --git a/website/docs/migrations/migrate-to-v0.30.md b/website/docs/migrations/migrate-to-v0.30.md new file mode 100644 index 000000000..deb395112 --- /dev/null +++ b/website/docs/migrations/migrate-to-v0.30.md @@ -0,0 +1,74 @@ +# Migrate to Lumos v0.30 + +## BREAKING: Buffer replaced by Uint8Array + +**Lumos can now run in browsers without any extra configs / polyfills with vite, webpack or create-react-app.** + +### `Buffer` was return type + +Methods / functions used to return a `Buffer` now returns a `Uint8Array`, e.g. In `@ckb-lumos/hd` + +```diff +- export function privateToPublic(privateKey: Buffer | HexString): Buffer | HexString ++ export function privateToPublic(privateKey: Uint8Array | HexString): Uint8Array | HexString + +- export function mnemonicToSeedSync(mnemonic = "", password = ""): Buffer ++ export function mnemonicToSeedSync(mnemonic = "", password = ""): Uint8Array + +- export function mnemonicToSeed(mnemonic = "", password = ""): Promise ++ export function mnemonicToSeed(mnemonic = "", password = ""): Promise +``` + +You can use the `hexify` method from `@ckb-lumos/lumos/codec` to replace `buffer.toString('hex')` + +```diff +- "0x" + privateToPublick(privKey).toString('hex') ++ hexify(privateToPublic(privKey)) +``` + +**Notice:** `hexify` returns `HexString` which starts with `'0x'` while `buffer.toString('hex')` result has **no** `'0x'` prefix. + +Same for `@ckb-lumos/hd/KeyStore` + +```diff +export default class Keystore { + ... +- derivedKey(password: string): Buffer ++ derivedKey(password: string): Uint8Array + ... +} +``` + +### `Buffer` was parameter type + +You can still pass in `Buffer` because `Buffer` is a subclass of `Uint8Array`, but using `Uint8Array` is recomended. + +`@ckb-lumos/hd/KeyChain` + +```diff +export default class Keychain { + ... +- constructor(privateKey: Buffer, chainCode: Buffer) ++ constructor(privateKey: Uint8Array, chainCode: Uint8Array) + ... +- hash160(data: Buffer): Buffer ++ hash160(data: Uint8Array): Uint8Array +} +``` + +`@ckb-lumos/hd/KeyStore` + +```diff +export default class Keystore { + ... + static create( + extendedPrivateKey: ExtendedPrivateKey, + password: string, +- options: { salt?: Buffer; iv?: Buffer } = {} ++ options: { salt?: Uint8Array; iv?: Uint8Array } = {} + ): Keystore + ... +- static mac(derivedKey: Buffer, ciphertext: Buffer): HexStringWithoutPrefix ++ static mac(derivedKey: Uint8Array, ciphertext: Uint8Array): HexStringWithoutPrefix +} +``` diff --git a/website/docs/recipes/cra-vite-webpack-or-other.md b/website/docs/recipes/cra-vite-webpack-or-other.md deleted file mode 100644 index 62f2feb47..000000000 --- a/website/docs/recipes/cra-vite-webpack-or-other.md +++ /dev/null @@ -1,177 +0,0 @@ -# CRA, Vite, Webpack or Other - -## Webpack 5.x - -In Webpack V5, it doesn't provide default polyfills for NodeJS API. You need to add the following config to -your `webpack.config.js` -.([Webpack `resolve.fallback` official document](https://webpack.js.org/configuration/resolve/#resolvefallback)) - -- install `crypto-browserify` and `buffer` dependencies. - -```bash -npm install -D crypto-browserify buffer -# or use yarn -yarn install -D crypto-browserify buffer -``` - -- add `resolve.fallback` to tell Webpack where to find the polyfills. -- add `webpack.ProvidePlugin` to tell Webpack to inject the polyfills to the global scope. - -Update your `webpack.config.js`: - -```js -module.exports = { - // ...other config - resolve: { - fallback: { - crypto: require.resolve("crypto-browserify"), - buffer: require.resolve("buffer/"), - path: false, - stream: false, - }, - }, - - plugins: [ - // ...your origin plugin for webpack - new webpack.ProvidePlugin({ Buffer: ["buffer", "Buffer"] }), - ], -} -``` - -## Create React App - -[Create React App](https://create-react-app.dev/) build system based on Webpack, but need some patch -via `react-app-rewired` - -First install `react-app-rewired`, `crypto-browserify` and `buffer` dependencies. - -```bash -npm install -D react-app-rewired crypto-browserify buffer -# or use yarn -yarn install -D react-app-rewired crypto-browserify buffer -``` - -Then create a `config-overrides.js` file in yout root directory of project. and add the following code to it. - -```js -const webpack = require("webpack") -module.exports = function override(config, env) { - config.resolve.fallback = { - ...config.resolve.fallback, - crypto: require.resolve("crypto-browserify"), - buffer: require.resolve("buffer/"), - path: false, - stream: false, - } - - config.plugins = [...config.plugins, new webpack.ProvidePlugin({ Buffer: ["buffer", "Buffer"] })] - - return config -} -``` - -Finally, override the `scripts` field in `package.json` to use `react-app-rewired`. - -```json -{ - "scripts": { - "start": "react-app-rewired start", - "build": "react-app-rewired build", - "test": "react-app-rewired test" - } -} -``` - -Also, [eject `create-react-app`](https://create-react-app.dev/docs/available-scripts/#npm-run-eject) is available, -after do it, see [Webpack polyfills Section](#Webpack) to config. - -## Vite - -Please follow these step. - -- add [rollup-plugin-polyfill-node](https://www.npmjs.com/package/rollup-plugin-polyfill-node) and - [@rollup/plugin-inject](https://www.npmjs.com/package/@rollup/plugin-inject) - -``` -npm install -D rollup-plugin-polyfill-node @rollup/plugin-inject -``` - -- config `vite.config.js` - -```js -import { defineConfig } from "vite" -import react from "@vitejs/plugin-react" -import inject from "@rollup/plugin-inject" -import nodePolyfills from "rollup-plugin-polyfill-node" -// https://vitejs.dev/config/ -export default defineConfig({ - plugins: [ - react(), - // add node polyfills - nodePolyfills(), - - // inject Buffer to global - inject({ - Buffer: ["buffer", "Buffer"], - }), - ], -}) -``` - -## Next.js - -Next.js supports customizing the webpack config in `nextjs.config.mjs` - -```js -import { createRequire } from "node:module" - -const require = createRequire(import.meta.url) - -/** @type {import('next').NextConfig} */ -const nextConfig = { - webpack: (config, { buildId, dev, isServer, defaultLoaders, nextRuntime, webpack }) => { - config.resolve.fallback = { - ...config.resolve.fallback, - crypto: require.resolve("crypto-browserify"), - buffer: require.resolve("buffer/"), - path: false, - stream: false, - } - - config.plugins = [...config.plugins, new webpack.ProvidePlugin({ Buffer: ["buffer", "Buffer"] })] - return config - }, -} - -export default nextConfig -``` - -## Docusaurus - -Docusaurus also packs project via webpack, so we just need to tell Docusaurus webpack that the following configuration -needs to be added - -```js -// docusaurus.config.js - -module.exports = { - plugins: [ - () => ({ - name: "node-polyfill", - configureWebpack() { - return { - resolve: { - fallback: { - crypto: require.resolve("crypto-browserify"), - buffer: require.resolve("buffer/"), - path: false, - stream: false, - }, - }, - plugins: [new webpack.ProvidePlugin({ Buffer: ["buffer", "Buffer"] })], - } - }, - }), - ], -} -```