Parcel-transformer-assemblyscript-codument NPM

AssemblyScript transformer for Parcel bundler

Preface

The idea behind this Parcel transformer is to integrate development of WASM-modules in AssemblyScript into the convenient web development process provided by Parcel.

Currently only works with web applications running in the browser. Support for NodeJS will be added later. Hopefully.

Quick start

For a quick start, there's a set of project templates with everything prepared for you to start developing within a minute or two.
Please see the AssemblyScript Parcel project templates package.

Installation

npm

npm install --save-dev parcel-transformer-assemblyscript-codument
npm install --save-dev parcel-config-assemblyscript-codument

yarn

yarn add -D parcel-transformer-assemblyscript-codument
yarn add -D parcel-config-assemblyscript-codument

Your project directory structure

Directories and files, overview

The following directories are expected to be part of a project that uses AssemblyScript and this Parcel transformer: D is a directory, F is a file.

D assembly -- Mandatory, all the AssemblyScript source code must be located here.
- F index.as.ts -- Mandatory, the entry point to your WASM module.
- F tsconfig.json -- Mandatory, contains AssemblyScript-specific settings for TypeScript.
D dist -- Autogenerated. The output directory for the compiled Parcel project (including the WASM module)
D src -- Optional, the source code of the project (TypeScript, JavaScript, etc.)
- F wasm-module.d.ts -- Autogenerated, the type definition file for your WASM module. The name and location of the file can be customised.
F .parcelrc -- Mandatory, the Parcel configuration file.
F as-codument-config.json -- Optional, the configuration file for this Parcel transformer (allows enabling extra logging, etc.)
F asconfig.json -- Optional, the configuration file for AssemblyScript compiler
F output.wasm.map -- Autogenerated, the source map for the WASM module.
F tsconfig.json -- Optional, the configuration file for your TypeScript compiler

File `assembly/index.as.ts`

The entry point to the WASM module must be in file /assembly/index.as.ts.
All the AssemblyScript files must be located under /assembly.
There can be subdirectories in /assembly.
The only file that needs to have the as.ts extension is index.as.ts, all the other files with your AssemblyScript code can simply have extension .ts.

File `assembly/tsconfig.json`

Contains AssemblyScript-specific settings for TypeScript and is necessary for the project to work.

{
  "extends": "assemblyscript/std/assembly.json",
  "include": [
    "./**/*.ts"
  ]
}

File `.parcelrc`

The essential configuration to make the Parcel build process work with AssemblyScript. The file must contain at least the following:

{
  "extends": [
    "@parcel/config-default",
    "parcel-config-assemblyscript-codument"
  ]
}

File `as-codument-config.json`

This file is optional, by default logging and statistics are disabled. By default, the TypeScript definitions are saved in ./src/wasm-module.d.ts

{
  "consoleLogs": "off",
  "displayStats": "on",
  ".d.ts_path": "./src/wasm-module.d.ts",
  "dropDebugStatements": {
    "development": "off",
    "production": "on"
  }
}

consoleLogs -- Whether to log transformer debug information to your terminal: "on" | "off"
displayStats -- Whether to display statistics of AssemblyScript compilation: "on" | "off"
d.ts_path -- Path to the TypeScript definition file with types for your WASM-functions.
dropDebugStatements.development -- Whether to remove debug statements from the development build: "on" | "off"
dropDebugStatements.production -- Whether to remove debug statements from the production build: "on" | "off"

For more details on dropDebugStatements.* please see Debug code preprocessing in this README.

File `asconfig.json`

An AssemblyScript configuration file, as described in the AssemblyScript documentation. NB: "outFile" setting in asconfig.json is ignored. Also, please don't set "entries".

asconfig.json must contain two targets: "debug" and "release". Each will be used depending on whether you command Parcel to produce a development or a production build.

As of version 2.9.x, Parcel can work only with "bindings": "raw", so even if you set "bindings": "esm", esm will be overwritten with raw internally. Here's an example of a valid asconfig.json that can be used as a starting point:

{
  "targets": {
    "debug": {
      "sourceMap": true,
      "shrinkLevel": 0,
      "debug": true
    },
    "release": {
      "sourceMap": false,
      "optimizeLevel": 3,
      "shrinkLevel": 2,
      "converge": false,
      "noAssert": false,
      "debug": false
    }
  },
  "options": {
    "bindings": "raw"
  }
}

If no asconfig.json is present, sensible defaults will be used instead.

File `output.wasm.map`

An autogenerated source map for your AssemblyScript code / WASM module. Unfortunately, as of Parcel version 2.9.x, the source maps are not yet supported. The team behind Parcel might enable AssemblyScript source maps support in the future. Stay tuned!

Development and release/production build

Development

Development builds reside in memory, no files are written to disk. To start a development server use:

parcel index.html

In this case changes in your AssemblyScript code will be picked up automatically and the HTML document will be reloaded by your browser.

Release/production

parcel build index.html

Debug code preprocessing

You can use //#dbg-start and //#dbg-end to wrap code that should be ignored during the build, if configured so.

Use cases:

When you have complex .toString() methods in your AssemblyScript code that you want to use for debugging but don't want to include them to your production build.
When you want to use some helper functions in your AssemblyScript code for debugging purposes but don't want to include them to your production build.
When you want to ignore import statements in your AssemblyScript code that are used for debugging purposes (e.g. for importing functions mentioned in point 2 above).
When you want all the console.log() and similar calls not to be compiled into your build.

Here's a minimal example:

import {somethingUseful} from "./something-useful";

//#dbg-start
// With default configuration this import won't happen on `yarn build`, it only happens on `yarn start`!
import {debugOnlyHelper} from "./debug-only-helper";

//#dbg-end

export function main(): void {

    console.log("[WASM] Hi there!");

    //#dbg-start
    //--------------------------------------------------------------------------
    // This code will not be compiled into your production build
    // because it is enclosed between the opening and closing debug comments.
    debugOnlyHelper();
    console.log(">>> This text will not be printed in a production build.");
    console.log(">>> It will be completely removed by the preporcessor.");
    //--------------------------------------------------------------------------
    //#dbg-end
}

Troubleshooting the debug code preprocessing

If you changed dropDebugStatements.development or dropDebugStatements.production in as-codument-config.json but the changes don't seem to have any effect, please delete directories .parcel-cache and dist in your root project directory and rebuild your project. That should solve the issue, given that your configuration file as-codument-config.json is valid.