diff --git a/README.md b/README.md index 5872175..b0c4cfc 100644 --- a/README.md +++ b/README.md @@ -131,6 +131,10 @@ To include the types for Harmony 24, do the following: > [!TIP] > You could also use this template to code in StoryboardPro by changing the path to `tba-types/StoryboardPro/24` +### Guides + +- [Install NPM packages like Moment.js](./guides/momentjs.md) + ## How Based on the above example, here is a diagram that shows the compilation/transpilation process (simplified): @@ -190,7 +194,8 @@ We use WebPack as the [module bundler](https://webpack.js.org/concepts/). This i Since ToonBoom Harmony's QtScript module system is not that advanced, it allows us to use ES modules (and CommonJS too) to split code into separate files without having to manually import files. -This also means that we can use and import NPM packages with Harmony! (if they use a compatible standard library thought). +> [!TIP] +> It means that we can import NPM packages and run them inside Harmony! Not all packages are compatible thought since we don't have the same Node/browser environment and APIs. For simple packages like Moment.js, see [this guide](./guides/momentjs.md). #### QtScript syntax fixes (custom Webpack plugin) @@ -208,6 +213,12 @@ var re = /[^\s(/]/; // Syntax error, / is not escaped Most of the time, those expressions are injected from corejs polyfills. In order to patch this, I created a custom [`FindReplacePlugin`](./webpack.config.ts#L15) for Webpack that does simple regex find/replace to fix those syntax errors. +## Known limitations + +- Some compiled JS bundle just crash in Harmony, I suspect it's a memory limit for the script context size ? +- You may need to add new rules in the `FindReplacePlugin` to handle special syntax. +- Very few NPM packages works within Harmony because most of the time they require a browser or node environment and the polyfills are not compatible. + ## Contributing This repo is just a template with an opinionated config. If you would like to contribute to the config itself, please open an issue! diff --git a/guides/momentjs.md b/guides/momentjs.md new file mode 100644 index 0000000..67e8722 --- /dev/null +++ b/guides/momentjs.md @@ -0,0 +1,31 @@ +# Moment.js + +This guide shows you how to install and use Moment.js, a popular date library in ToonBoom Harmony. + +Install it from NPM and create a new script file: + +```sh +❯ npm install moment +❯ touch ./src/scripts/moment.ts +``` + +Use ES modules to import the library: + +```ts +// src/scripts/moment.ts +import moment from "moment"; + +MessageLog.trace(moment().locale("es").format("LLLL")); +``` + +Build it: + +```sh +❯ npm run build +``` + +Then run `dist/moment.js` in Harmony: + +```txt +martes, 18 de noviembre de 2025 12:23 +``` diff --git a/webpack.config.ts b/webpack.config.ts index 39028ce..3b836cc 100644 --- a/webpack.config.ts +++ b/webpack.config.ts @@ -66,8 +66,13 @@ class FindReplacePlugin { const babelRule: RuleSetRule = { test: /\.(ts|js)$/, - // Excluding node_modules is really important to avoid Babel injecting corejs in corejs files themselves + // https://webpack.js.org/loaders/babel-loader/#exclude-libraries-that-should-not-be-transpiled exclude: /node_modules/, + // exclude: [ + // // \\ for Windows, / for macOS and Linux + // /node_modules[\\/]core-js/, + // /node_modules[\\/]webpack[\\/]buildin/, + // ], use: { loader: "babel-loader", options: { @@ -115,7 +120,9 @@ const config: Configuration = { rules: [babelRule], }, entry: getScriptsEntryObject(), - resolve: { extensions: [".ts", ".js"] }, + resolve: { + extensions: [".ts", ".js"], + }, output: { filename: "[name].js", path: path.resolve(__dirname, "dist"), @@ -139,6 +146,8 @@ const config: Configuration = { * Some Regexp uses "/" character in character sets but must be escaped in QtScript syntax (don't know why) */ { from: /\[\^\\s\(\/\]/g, to: "[^\\s(\\/]" }, + { from: /\[\\w\.\/\]/g, to: "[\\w.\\/]" }, + // [a-z_+-\/] ], }), ],