Welcome to the new Golem Cloud Docs! 👋
Documentation
Experimental Languages
TypeScript
Setting up the Golem TypeScript SDK

Setting up the Golem TypeScript SDK

⚠️

If the project was created with golem-cli 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