From 145f08f2d90a59cdd129b072b7d1907a974a89c3 Mon Sep 17 00:00:00 2001 From: Victor Oliva Date: Wed, 24 Jul 2024 17:15:32 +0200 Subject: [PATCH] feat: update codegen with latest changes --- docs/pages/codegen.md | 23 ++++++++++++++++------- docs/pages/getting-started.mdx | 4 ++-- 2 files changed, 18 insertions(+), 9 deletions(-) diff --git a/docs/pages/codegen.md b/docs/pages/codegen.md index e822421e..359f01f6 100644 --- a/docs/pages/codegen.md +++ b/docs/pages/codegen.md @@ -20,16 +20,19 @@ Options: -f, --file Source from metadata encoded file -w, --wsUrl Source from websocket URL -c, --chainSpec Source from chain spec file - -n, --name Source from a well-known chain (choices: "polkadot", "ksmcc3", "rococo_v2_2", "westend2") + -n, --name Source from a well-known chain (choices: "ksmcc3", "paseo", + "polkadot", "polkadot_collectives", "rococo_v2_2", "westend2", [...]") + --wasm Source from runtime wasm file --no-persist Do not persist the metadata as a file + --skip-codegen Skip running codegen after adding -h, --help display help for command ``` -`papi add` registers a new chain. It requires a key, which is the JS variable name the codegen will create, and a source (`-f`, `-w`, `-c`, or `-n`). The command stores this information for later use into a configuration file `polkadot-api.json` and then downloads the fresh metadata into a file `${key}.scale`. +`papi add` registers a new chain. It requires a key, which is the name of the constant the codegen will create, and a source (`-f`, `-w`, `-c`, `-n`, or `--wasm`). The command download the fresh metadata for that chain and stores this information for later use into a `.papi` folder, with a configuration file `polkadot-api.json` and the metadata file `${key}.scale`. You can add as many chains as you want, but each has to have a unique `key` (which must be a valid JS variable name). -The CLI can then be used to generate the type descriptors for all of the added chains through the `generate` command. +`papi add` by default runs codegen automatically. If you want to add multiple chains without having to rerun codegen, you can use the flag `--skip-codegen`, and then run `papi generate` command once you want to run the codegen. ```sh npx papi generate @@ -49,10 +52,14 @@ It's recommended to add `papi` to the `postinstall` script in package.json to ha } ``` -The code is generated into the `@polkadot-api/descriptors` node modules package +The code is generated into a [local package](https://docs.npmjs.com/cli/v9/configuring-npm/package-json/#local-paths) located in `.papi/descriptors`, which gets installed as a regular `@polkadot-api/descriptors` node modules package. + +The folder `.papi` should be added to your source control repository. The only thing that should be ignored are the generated files from the codegen (`.papi/descriptors/dist`), but for git, that's already ignored by a pre-configured `.gitignore` inside `.papi`. + +When the metadata is updated, the codegen will update the generated code and also the package version, to have package managers update the `@polkadot-api/descriptors` package. :::info -Some package managers clean the `node_modules` folder after installing or removing dependencies. When that happens, run the codegen again. +If you're using yarn v1, you might need to run `yarn --force` after a codegen for it to detect the change. ::: ## Contents @@ -67,11 +74,13 @@ The generated code contains all of the types extracted from the metadata of all - Constants - Every runtime call -These are consumed by `getTypedApi()`, which allows the IDE to reference any of these calls with autocompletion, etc. At runtime, it also contains the checksum of each of these calls, so that it can detect incompatibilities with the chain it's connected to. +These are consumed by `getTypedApi()`, which allows the IDE to reference any of these calls with autocompletion, etc. At runtime, it also contains a representation of the type for each of these calls, so that it can detect incompatibilities with the chain it's connected to. The types are anonymous (they don't have a name in the metadata), but PolkadotAPI has a directory of well-known types for some of the most widely used Enums. If a chain is using one of these well-known types, it's also generated and exported. -In the event that there are two chains with the two well-known types that have the same name but they are different, then the key is appended at the beginning of the type. For instance, if two chains `dot` and `ksm` might have a slightly different `PreimageRequestStatus`, in that case, the codegen exports `DotPreimageRequestStatus` and `KsmPreimageRequestStatus`. +:::warning +It's important to know that the descriptors exported by the codegen **should be treated as a black box**. When importing the descriptors of a chain, the type might not actually match what's in runtime, and its internals are subject to change. It has to be treated as an opaque token, passing it directly to `.getTypedApi()`. +::: ## Usage diff --git a/docs/pages/getting-started.mdx b/docs/pages/getting-started.mdx index b28d63f9..f6361ab7 100644 --- a/docs/pages/getting-started.mdx +++ b/docs/pages/getting-started.mdx @@ -2,10 +2,10 @@ import * as Tabs from "../components/Tabs" # Getting Started -Start by installing `polkadot-api` and `@polkadot-api/descriptors` +Start by installing `polkadot-api` ```sh -npm i polkadot-api @polkadot-api/descriptors +npm i polkadot-api ``` Next, download the latest metadata from the chain you want to connect to and generate the types: