Starter for AssemblyScript + TypeScript

This is a starter project for creating WASMs using AssemblyScript and interacting with it using TypeScript. Code can be shared between the two languages and it comes with two test frameworks as-pect for AssemblyScript and vitest for testing the TypeScript code.

The code can either be used on a static web page, or as a module, and it's bundled using vite.

AssemblyScript in assembly/ folder TypeScript in lib/ folder Shared code in shared/ folder

Get started

Install dependencies:

yarn install

Build the AssemblyScript code:

yarn asbuild

Start the dev server

yarn start

TypeScript code changes (in lib/ and shared/ folders) will be automatically reloaded by the browser on save. AssemblyScript changes (in assembly/ and shared/ folders) will require a manual rebuild using yarn asbuild.

Development

Prerequisites

yarn install

Automatically rebuild and test on save

To rebuild the WASM and run all tests on save, execute:

yarn dev

This will run the following commands in parallel:

yarn asbuild:debug-watch
yarn astest-watch
yarn libtest-watch
yarn sharedtest-watch
yarn start

Assembyscript

Write AssemblyScript code and tests in assembly/ and shared/ folders.

See the note below under Shared regarding the shared/ folder.

Test: Assembyscript

To run AssemblyScript tests for the AssemblyScript folder, execute one of the following:

yarn astest
yarn astest-watch

It will run tests in assembly/ and shared/ folders using as-pect.

Build: Assembyscript

To build the AssemblyScript folder, execute one of the following:

yarn asbuild
yarn asbuild-watch

The code will be built to the build/wasm/ folder.

TypeScript

Write TypeScript code and tests in lib/ and shared/ folders.

See the note below under Shared regarding the shared/ folder.

Test: TypeScript

To run TypeScript tests for the lib/ folder, execute one of the following:

yarn libtest
yarn libtest-watch
yarn libtest-coverage

It will run tests in lib/ using vitest

To run TypeScript tests for the shared/ folder, execute one of the following:

yarn sharedtest
yarn sharedtest-watch
yarn sharedtest-coverage

It will run tests in shared/ using vitest.

Build: TypeScript

To build the TypeScript in the lib/ and shared/ folders, execute:

yarn libbuild

The code will be built to the build/lib/ folder.

Shared

Code in shared/ folder is used by both AssemblyScript and TypeScript . By default it only supports the basic portable types and their conversion functions like i32 and i32(value), see as-minimal-portable for more details and information on how to enable more features or switch to the full portable library.

See the portability section in the AssemblyScript documentation for information om how to write portable code.

The shared folder is built and embedded in the wasm when used in the AssemblyScript code, and is converted to javascript when used in the TypeScript code.

Compile

This project can be compiled to a static web page or a node module.

Compile to a static web

To compile the project to a static web page, execute one of the following:

yarn build
yarn build-watch

Compile to a library

To compile to a library, execute one of the following:

yarn build-lib
yarn build-lib-watch

Debug WASM vs Release WASM

By default the debug version of the WASM is used when compiling and running tests. The version can be controlled by setting environment variable WASM=release or WASM=debug.

If environment variable NODE_ENV=production is set, or CI is set, and WASM hasn't been set, then the release version of the WASM is automatically used.

When compiling to a static web or library, the release version of the WASM is used, as vite sets NODE_ENV=production by default.

Optional: VS Code Setup to format AssemblyScript code

AssemblyScript can be formatted using prettier as long as decorators, such as @inline, on top level functions and variables aren't used. TypeScript only allows them on classes and its members. This is an example that prettier can't handle:

// @ts-ignore: decorator
@inline
export function add(a: i32, b: i32): i32 {
  return a + b;
}

To be able to format AssemblyScript code in VS Code on save, follow these steps to install a custom formatter that uses a few tricks so that prettier can format the code.

Install https://marketplace.visualstudio.com/items?itemName=jkillian.custom-local-formatters in VS Code

Install the formatter for assembly script

Yarn 1:

yarn add -D prettier https://github.com/HCanber/AssemblyScript-prettier

Yarn 2+:

yarn add -D prettier AssemblyScript-prettier@github:HCanber/AssemblyScript-prettier

NPM:

npm install -D prettier git+https://github.com/HCanber/AssemblyScript-prettier.git

Open .vscode/settings.json and uncomment the lines for the formatter

Now when AssemblyScript (and TypeScript) code is saved, it will be formatted using the newly installed formatter.

Optional: Format code on commits

Follow the steps for Prettier's Pre-commit Hook but change the prettier command to as-prettier instead.

HCanber/assemblyscript-ts-template