Welcome to the new Golem Cloud Docs! 👋
TypeScript Language Guide
Setting up the Golem TypeScript SDK

Setting up the Golem TypeScript SDK

⚠️

If the project was created with golem new, it already has the Golem TypeScript SDK set up and these steps can be ignored.

If setting up the Golem TypeScript SDK (opens in a new tab) manually, the following steps are required:

Create a new project

npm init

Ensure ESM is enabled

In your package.json file, ensure the type is set to module.

package.json
{
  "type": "module"
}

Install Dev Dependencies

The Golem TypeScript SDK currently relies on forked versions of jco (opens in a new tab) and componentize-js (opens in a new tab).

npm install --save-dev @golemcloud/componentize-js @golemcloud/golem-ts @golemcloud/jco @rollup/plugin-node-resolve@^15.2.3 rollup-plugin-typescript2@^0.36.0 @types/node@^20.14.2 rollup@^4.18.0 tslib@^2.6.3 typescript@^5.4.5

Add Rollup Config: rollup.config.mjs

To silence rollup warnings, add WIT imports to the external array.

rollup.config.mjs
import typescript from "rollup-plugin-typescript2"
import resolve from "@rollup/plugin-node-resolve"
 
export default {
  input: "src/main.ts",
  output: {
    file: "out/main.js",
    format: "esm",
  },
  external: [
    "golem:api/host@1.1.0",
    "golem:rpc/types@0.1.0",
    "wasi:blobstore/blobstore",
    "wasi:blobstore/container",
    "wasi:cli/environment@0.2.0",
    "wasi:clocks/wall-clock@0.2.0",
    "wasi:clocks/monotonic-clock@0.2.0",
    "wasi:filesystem/preopens@0.2.0",
    "wasi:filesystem/types@0.2.0",
    "wasi:http/types@0.2.0",
    "wasi:http/outgoing-handler@0.2.0",
    "wasi:io/error@0.2.0",
    "wasi:io/poll@0.2.0",
    "wasi:io/streams@0.2.0",
    "wasi:keyvalue/eventual-batch@0.1.0",
    "wasi:keyvalue/eventual@0.1.0",
    "wasi:logging/logging",
    "wasi:random/random@0.2.0",
    "wasi:random/insecure@0.2.0",
    "wasi:random/insecure-seed@0.2.0",
    "wasi:sockets/ip-name-lookup@0.2.0",
    "wasi:sockets/instance-network@0.2.0",
  ],
  plugins: [resolve(), typescript()],
}

Add Typescript Config: tsconfig.json

tsconfig.json
{
  "$schema": "https://json.schemastore.org/tsconfig",
  "compilerOptions": {
    "skipLibCheck": true,
    "target": "ES2020",
    "noEmit": true,
    "lib": ["ES2020"],
    "types": ["node"],
    "moduleResolution": "bundler",
    "checkJs": false,
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true
  },
  "exclude": ["node_modules"],
  "include": ["src/**/*.ts"]
}

Add scripts to package.json

Add the following scripts to your package.json:

package.json
{
  "scripts": {
    "stub": "jco stubgen wit -o src/generated",
    "build": "rollup --config",
    "componentize": "npm run stub && npm run build && jco componentize -w wit -o out/component_name.wasm out/main.js",
    "clean": "rm -rf out src/generated"
  }
}
  • stub - Generates the TypeScript declaration (.d.ts) files containing stubs for the WIT files.
  • build - Compiles the TypeScript code into JavaScript.
  • componentize - Bundles the JavaScript code into a WebAssembly module.
  • clean - Cleans up the project by removing the generated files.

Verify package.json

Ensure the scripts and devDependencies sections are correct (versions may differ).

package.json
{
  "type": "module",
  "scripts": {
    "stub": "jco stubgen wit -o src/generated",
    "build": "rollup --config",
    "componentize": "npm run stub && npm run build && jco componentize -w wit -o out/component_name.wasm out/main.js",
    "clean": "rm -rf out src/generated"
  },
  "devDependencies": {
    "@golemcloud/componentize-js": "0.10.5-golem.3",
    "@golemcloud/golem-ts": "1.1.0",
    "@golemcloud/jco": "1.4.4-golem.1",
    "@rollup/plugin-node-resolve": "^15.2.3",
    "rollup-plugin-typescript2": "^0.36.0",
    "@types/node": "^20.14.2",
    "rollup": "^4.18.0",
    "tslib": "^2.6.3"
  }
}

Add all the supported WIT files into the project

The project's wit/deps directory must contain all the WIT files from the golem-wit (opens in a new tab) repository.

Either clone the repository and copy the wit/deps directory into your project, or run the following command to download the WIT files:

curl -L https://github.com/golemcloud/golem-wit/archive/refs/heads/main.zip | tar -xvf- -C . --strip-components=2 "golem-wit-main/wit/deps" && mkdir -p ./wit/deps && mv deps/* ./wit/deps/ && rm -rf deps/

The resulting directory structure should look like this:

    • main.wit

    • Importing WITs into the component's world:

    If the project's WIT file was like this:

    package golem:demo;
 
world ts-example {
  export api;
}

    Modify it in the following way:

    package golem:demo;
 
world ts-example {
  import golem:api/host@1.1.0;
  import golem:rpc/types@0.1.0;
 
  import wasi:blobstore/blobstore;
  import wasi:blobstore/container;
  import wasi:cli/environment@0.2.0;
  import wasi:clocks/wall-clock@0.2.0;
  import wasi:clocks/monotonic-clock@0.2.0;
  import wasi:filesystem/preopens@0.2.0;
  import wasi:filesystem/types@0.2.0;
  import wasi:http/types@0.2.0;
  import wasi:http/outgoing-handler@0.2.0;
  import wasi:io/error@0.2.0;
  import wasi:io/poll@0.2.0;
  import wasi:io/streams@0.2.0;
  import wasi:keyvalue/eventual-batch@0.1.0;
  import wasi:keyvalue/eventual@0.1.0;
  import wasi:logging/logging;
  import wasi:random/random@0.2.0;
  import wasi:random/insecure@0.2.0;
  import wasi:random/insecure-seed@0.2.0;
  import wasi:sockets/ip-name-lookup@0.2.0;
  import wasi:sockets/instance-network@0.2.0;
 
  export api;
}

    Run stub script

    This will generate Typescript declaration files in the src/generated directory, for all imported WIT interfaces.

    npm run stub
    Next StepsHTTP client