@metamask/snaps-cli 1.0.2 → 2.0.1

package/README.md

@@ -7,10 +7,10 @@ A CLI for developing MetaMask Snaps.
 Use Node.js `16.0.0` or later.
 We recommend [nvm](https://github.com/nvm-sh/nvm) for managing Node.js versions.
 
-Install a dev dependency in your snap project or globally using `yarn` or `npm`:
+Install a dev dependency in your snap project using `yarn` or `npm`:
 
-- `npm install -g @metamask/snaps-cli`
-- `yarn global add @metamask/snaps-cli`
+- `npm install --save-dev @metamask/snaps-cli`
+- `yarn add -D @metamask/snaps-cli`
 
 ## Usage
 
@@ -18,55 +18,55 @@ Install a dev dependency in your snap project or globally using `yarn` or `npm`:
 Usage: mm-snap <command> [options]
 
 Commands:
-  mm-snap build             Build Snap from source                  [aliases: b]
-  mm-snap eval              Attempt to evaluate Snap bundle in SES  [aliases: e]
-  mm-snap init [directory]  Initialize Snap package                 [aliases: i]
-  mm-snap manifest          Validate the snap.manifest.json file    [aliases: m]
-  mm-snap serve             Locally serve Snap file(s) for testing  [aliases: s]
-  mm-snap watch             Build Snap on change                    [aliases: w]
+  mm-snap build     Build snap from source                          [aliases: b]
+  mm-snap eval      Attempt to evaluate snap bundle in SES          [aliases: e]
+  mm-snap manifest  Validate the snap.manifest.json file            [aliases: m]
+  mm-snap serve     Locally serve Snap file(s) for testing          [aliases: s]
+  mm-snap watch     Build Snap on change                            [aliases: w]
 
 Options:
       --version           Show version number                          [boolean]
-      --verboseErrors     Display original errors      [boolean] [default: true]
-      --suppressWarnings  Whether to suppress warnings[boolean] [default: false]
+  -c, --config            Path to config file                           [string]
+      --verboseErrors     Display original errors         [deprecated] [boolean]
+      --suppressWarnings  Whether to suppress warnings    [deprecated] [boolean]
   -h, --help              Show help                                    [boolean]
 
 Examples:
-  mm-snap init                              Initialize a snap project in the
-                                            current directory
-  mm-snap init my-snap                      Initialize a snap project in the
-                                            'my-snap' directory
-  mm-snap build -s src/index.js -d out      Build 'src/index.js' as
-                                            './out/bundle.js'
-  mm-snap build -s src/index.js -d out -n   Build 'src/index.js' as
-  snap.js                                   './out/snap.js'
-  mm-snap serve -r out                      Serve files in './out' on port 8080
-  mm-snap serve -r out -p 9000              Serve files in './out' on port 9000
-  mm-snap watch -s src/index.js -d out      Rebuild './out/bundle.js' on changes
-                                            to files in 'src/index.js' parent
-                                            and child directories
+  mm-snap build                             Build './src/index.js' as
+                                            './dist/bundle.js'
+  mm-snap build --config                    Build './src/index.js' as
+  ./snap.config.build.ts                    './dist/bundle.js' using the config
+                                            in './snap.config.build.ts'
+  mm-snap manifest --fix                    Check the snap manifest, and fix any
+                                            errors
+  mm-snap watch --port 8000                 The snap input file for changes, and
+                                            serve it on port 8000
+  mm-snap serve --port 8000                 Serve the snap bundle on port 8000
 ```
 
 ## MetaMask Snaps
 
-MetaMask Snaps enables trustlessly extending the functionality of MetaMask at runtime.
-A Snap consist of two things: a JSON manifest and a JavaScript bundle.
-At present, Snaps can be published as npm packages on the public npm registry, or hosted locally during development.
-In the future, it will be possible to publish snaps on many different platforms, including arbitrary npm registries and IPFS.
+MetaMask Snaps enables trustlessly extending the functionality of MetaMask at
+runtime. A snap consist of two things: a JSON manifest and a JavaScript bundle.
+At present, snaps can be published as npm packages on the public npm registry,
+or hosted locally during development. In the future, it will be possible to
+publish snaps on many different platforms, including arbitrary npm registries
+and IPFS.
 
-We recommend building your Snap using this tool.
-You can bundle your Snap using your own tools, but it must run in SES and only use the global APIs that MetaMask exposes at runtime.
-Although Snaps currently execute in the browser, some browser APIs are not available to Snaps, and Snaps do not have DOM access.
+We recommend building your snap using this tool. You can bundle your snap using
+your own tools, but it must run in SES and only use the global APIs that
+MetaMask exposes at runtime. Although snaps currently execute in the browser,
+some browser APIs are not available to snaps, and snaps do not have DOM access.
 
 ### The Snap Manifest
 
-Your manifest must be named `snap.manifest.json` and located in the root directory of your npm package.
-Here's an example manifest:
+Your manifest must be named `snap.manifest.json` and located in the root
+directory of your npm package. Here's an example manifest:
 
 ```json
 {
   "version": "0.7.0",
-  "proposedName": "@metamask/template-snap",
+  "proposedName": "Dialog Example",
   "description": "A MetaMask Snap template.",
   "repository": {
     "type": "git",
@@ -84,15 +84,21 @@ Here's an example manifest:
     }
   },
   "initialPermissions": {
-    "snap_confirm": {}
+    "snap_dialog": {},
+    "endowment:rpc": {
+      "dapps": true,
+      "snaps": false
+    }
   },
   "manifestVersion": "0.1"
 }
 ```
 
-Refer to [the Snaps publishing specification](https://github.com/MetaMask/specifications/blob/main/snaps/publishing.md) and the [manifest JSON schema](https://github.com/MetaMask/snaps-monorepo/blob/main/packages/controllers/src/snaps/json-schemas/snap-manifest.schema.json) for details.
+Refer to [the Snaps publishing specification](https://github.com/MetaMask/specifications/blob/main/snaps/publishing.md)
+for more information about the manifest.
 
-> **ATTN:** If your Snap is not compatible with the publishing specification, your Snap may not work properly or install at all.
+> **Note**: If your snap is not compatible with the publishing specification,
+> your snap may not work properly or install at all.
 
 ### Assumed Project Structure
 
@@ -109,56 +115,529 @@ snap-project/
 ├─ ... (all other project files and folders)
 ```
 
-Source files other than `index.js` are located through its imports.
-The defaults can be overwritten using the `snap.config.js` [config file](#configuration-file).
+Source files other than `index.js` are located through its imports. The
+defaults can be overwritten using the `snap.config.js` or (`snap.config.ts`)
+[config file](#configuration-file).
+
+## Configuration
+
+The MetaMask Snaps CLI supports a configuration file. It can be either:
 
-### Configuration File
+- `snap.config.js` - a CommonJS module.
+- `snap.config.ts` - a TypeScript module.
 
-`snap.config.js` should be placed in the project root directory. It can override cli options - the property `cliOptions` should have string keys matching command arguments. Values become argument defaults, which can still be overridden on the command line.
+The file should be placed in the project root directory.
 
-Example:
+### Example
+
+#### JavaScript
 
 ```javascript
 module.exports = {
-  cliOptions: {
-    src: 'lib/index.js',
-    dist: 'out',
+  bundler: 'webpack', // default: 'browserify'
+  input: 'src/index.js',
+  output: {
+    path: 'dist',
+  },
+  server: {
     port: 9000,
   },
 };
 ```
 
-If you want to customize the Browserify build process, you can provide `bundlerCustomizer` property. It's a function that takes one argument - [browserify object](https://github.com/browserify/browserify#api-example) which we use internally to bundle the snap. You can transform it in any way you want, for example adding plugins.
+#### TypeScript
 
-Example:
+The CLI has full support for TypeScript out of the box. `@metamask/snaps-cli`
+exports a `SnapConfig` type that can be used to type the configuration object.
 
-```javascript
-const brfs = require('brfs');
+```typescript
+import type { SnapConfig } from '@metamask/snaps-cli';
 
-module.exports = {
-  cliOptions: {
-    /* ... */
+const config: SnapConfig = {
+  bundler: 'webpack', // default: 'browserify'
+  input: 'src/index.js',
+  output: {
+    path: 'dist',
   },
-  bundlerCustomizer: (bundler) => {
-    bundler.transform(brfs);
+  server: {
+    port: 9000,
   },
 };
+
+export default config;
 ```
 
 The configuration file should not be published.
 
-### Gotchas
-
-- Commands
-  - `watch --src ... --dist ...` rebuilds on all changes in the parent directory
-    of `src` and its children except:
-    - `node_modules/`
-    - `test/`, `tests/`, `**/*.test.js`, and `**/*.test.ts`
-    - The specified `dist` directory
-    - Dotfiles
-  - `serve --root ... --port ...` serves the `root` directory on `localhost:port`
-    - By default, `root` serves the current working directory: `.`
-- Arguments
-  - `src` must be a file path when specified
-  - `dist` and `root` must be directory paths when specified
-  - `transpilationMode` must be at least `localOnly` for TypeScript Snaps
+### Options
+
+- [`bundler`](#bundler)
+- [`input`](#input)
+- [`output`](#output)
+  - [`output.path`](#outputpath)
+  - [`output.filename`](#outputfilename)
+  - [`output.clean`](#outputclean)
+  - [`output.minimize`](#outputminimize)
+- [`server`](#server)
+  - [`server.enabled`](#serverenabled)
+  - [`server.root`](#serverroot)
+  - [`server.port`](#serverport)
+- [`environment`](#environment)
+- [`stats`](#stats)
+  - [`stats.verbose`](#statsverbose)
+  - [`stats.builtIns`](#statsbuiltins)
+  - [`stats.buffer`](#statsbuffer)
+- [`customizeWebpackConfig`](#customizewebpackconfig)
+- [`experimental`](#experimental)
+  - [`experimental.wasm`](#experimentalwasm)
+
+#### `bundler`
+
+- Type: `"browserify"` | `"webpack"`
+- Default: `"browserify"`
+
+The bundler to use. The MetaMask Snaps CLI supports both Browserify and
+Webpack. For backwards compatibility, Browserify is the default, but we
+recommend using Webpack. Browserify support will be removed in the future.
+
+This section describes the options for the Webpack bundler. For Browserify,
+refer to the [legacy options](#legacy-options) section.
+
+#### `input`
+
+- Type: `string`
+- Default: `"src/index.js"`
+
+The entry point of your snap. This is the file that will be bundled.
+
+#### `output`
+
+- Type: `object`
+
+The output configuration.
+
+##### `output.path`
+
+- Type: `string`
+- Default: `"dist"`
+
+The output directory.
+
+##### `output.filename`
+
+- Type: `string`
+- Default: `"bundle.js"`
+
+The output filename.
+
+##### `output.clean`
+
+- Type: `boolean`
+- Default: `false`
+
+Whether to clean the output directory before building.
+
+##### `output.minimize`
+
+- Type: `boolean`
+- Default: `true`
+
+Whether to minimize the bundle. This will remove comments and whitespace from
+the bundle, mangle variable names, and perform other optimizations.
+
+#### `sourceMap`
+
+- Type: `boolean | "inline"`
+- Default: `true`
+
+Whether to generate a source map. If `"inline"`, the source map will be
+inlined in the bundle. Otherwise, it will be written to a separate file.
+
+#### `evaluate`
+
+- Type: `boolean`
+
+Whether to evaluate the bundle. This will check the bundle for compatibility
+issues with the MetaMask Snaps runtime. If there are any issues, the CLI will
+exit with an error.
+
+#### `manifest`
+
+- Type: `object`
+
+The snap manifest configuration.
+
+##### `manifest.path`
+
+- Type: `string`
+- Default: `"snap.manifest.json"`
+
+The path to the snap manifest, i.e., `snap.manifest.json`.
+
+##### `manifest.update`
+
+- Type: `boolean`
+- Default: `true`
+
+Whether to update the manifest with the bundle shasum, and any other possible
+updates. If `false`, the manifest will not be updated, and an error will be
+thrown if the manifest is not up-to-date.
+
+#### `server`
+
+- Type: `object`
+
+The development server configuration. The development server is used to test
+your snap during development, using the `watch` and `serve` commands.
+
+##### `server.enabled`
+
+- Type: `boolean`
+- Default: `true`
+
+Whether to enable the development server. If `false`, the development server
+will not be started when running the `watch` command. This option has no effect
+on the `serve` command.
+
+##### `server.root`
+
+- Type: `string`
+- Default: `process.cwd()`
+
+The root directory of the development server. This is the directory that will
+be served by the development server.
+
+##### `server.port`
+
+- Type: `number`
+- Default: `8081`
+
+The port to run the development server on. If set to `0`, a random port will
+be used.
+
+#### `environment`
+
+- Type: `Record<string, unknown>`
+
+The environment configuration. This is used to set environment variables for
+the snap, which can be accessed using `process.env`.
+
+In addition to the environment variables set by the user, the following
+environment variables are set by the CLI:
+
+- `NODE_ENV` - `"production"`.
+- `NODE_DEBUG` - `false`.
+- `DEBUG` - `false`.
+
+#### `stats`
+
+- Type: `object`
+
+The stats configuration, which controls the log output of the CLI.
+
+##### `stats.verbose`
+
+- Type: `boolean`
+- Default: `false`
+
+Whether to enable verbose logging. If `true`, the CLI will log more
+information.
+
+##### `stats.builtIns`
+
+- Type: `false | object`
+- Default: `{ ignore: [] }`
+
+Whether to check for missing built-in modules. The MetaMask Snaps CLI does not
+support Node.js built-ins out of the box, and any used built-ins must be
+provided through the `customizeWebpackConfig` option. When enabled, the CLI
+shows a warning if a built-in module is used, but not provided.
+
+###### `stats.builtIns.ignore`
+
+- Type: `string[]`
+
+A list of built-in modules to ignore. This is useful if the built-in module is
+not actually used in the snap, but is added by a dependency.
+
+###### `stats.buffer`
+
+- Type: `boolean`
+- Default: `true`
+
+Whether to show a warning if `Buffer` is used, but not provided. The `Buffer`
+global is not available in the MetaMask Snaps runtime by default, and must
+be provided through the `customizeWebpackConfig` option.
+
+#### `customizeWebpackConfig`
+
+- Type: `(config: webpack.Configuration) => webpack.Configuration`
+
+A function that can be used to customize the Webpack configuration. This is
+useful if you need to add a Webpack plugin, provide a polyfill, add a loader,
+and so on.
+
+The function receives the Webpack configuration object, and should return the
+modified configuration object. For convenience, `@metamask/snaps-cli` exports
+a `merge` function (re-exported from `webpack-merge`) that can be used to merge
+the configuration object with the default configuration.
+
+The default configuration can be found in [`src/webpack/config.ts`](./src/webpack/config.ts).
+
+```typescript
+import type { SnapConfig } from '@metamask/snaps-cli';
+import { merge } from '@metamask/snaps-cli';
+
+const config: SnapConfig = {
+  customizeWebpackConfig: (config) =>
+    merge(config, {
+      plugins: [
+        // Add a plugin.
+      ],
+      module: {
+        rules: [
+          // Add a loader.
+        ],
+      },
+    }),
+};
+
+export default config;
+```
+
+#### `experimental`
+
+- Type: `object`
+
+Experimental features. These features are not stable, and may change in the
+future.
+
+##### `experimental.wasm`
+
+- Type: `boolean`
+
+Whether to enable WebAssembly support. When this is enabled, WebAssembly files
+can be imported in the snap, for example:
+
+```typescript
+import program from './program.wasm';
+
+const module = await WebAssembly.instantiate(program, {});
+// ...
+```
+
+### Legacy Options
+
+> **Warning**: Using the Browserify-based build system is deprecated, and will
+> be removed in a future version. Please migrate to the Webpack-based build
+> system.
+
+- [`bundler`](#bundler)
+- [`cliOptions`](#clioptions)
+  - [`cliOptions.bundle`](#clioptionsbundle)
+  - [`cliOptions.dist`](#clioptionsdist)
+  - [`cliOptions.eval`](#clioptionseval)
+  - [`cliOptions.manifest`](#clioptionsmanifest)
+  - [`cliOptions.outfileName`](#clioptionsoutfilename)
+  - [`cliOptions.port`](#clioptionsport)
+  - [`cliOptions.root`](#clioptionsroot)
+  - [`cliOptions.sourceMaps`](#clioptionssourcemaps)
+  - [`cliOptions.src`](#clioptionssrc)
+  - [`cliOptions.stripComments`](#clioptionsstripcomments)
+  - [`cliOptions.transpilationMode`](#clioptionstranspilationmode)
+  - [`cliOptions.depsToTranspile`](#clioptionsdepstotranspile)
+  - [`cliOptions.writeManifest`](#clioptionswritemanifest)
+  - [`cliOptions.serve`](#clioptionsserve)
+  - [`cliOptions.verboseErrors`](#clioptionsverboseerrors)
+  - [`cliOptions.suppressWarnings`](#clioptionssuppresswarnings)
+- [`bundlerCustomizer`](#bundlercustomizer)
+
+#### `bundler`
+
+- Type: `"browserify"` | `"webpack"`
+- Default: `"browserify"`
+
+The bundler to use. The MetaMask Snaps CLI supports both Browserify and
+Webpack. For backwards compatibility, Browserify is the default, but we
+recommend using Webpack. Browserify support will be removed in the future.
+
+This section describes the options for the Browserify bundler. For Webpack,
+refer to the [options](#options) section.
+
+#### `cliOptions`
+
+- Type: `object`
+
+The CLI options. These can be specified using the CLI, but can also be
+specified in the configuration file. For example, the `--port` option can be
+specified in the configuration file as follows:
+
+```ts
+export default {
+  cliOptions: {
+    port: 8081,
+  },
+};
+```
+
+But can also be specified using the CLI:
+
+```bash
+$ mm-snap serve --port 8081
+```
+
+If the same option is specified in both the configuration file and the CLI,
+the CLI option takes precedence.
+
+##### `cliOptions.bundle`
+
+- Type: `string`
+- Default: `dist/bundle.js`
+
+The path to the bundle file. This is where the bundle will be written to.
+
+##### `cliOptions.dist`
+
+- Type: `string`
+- Default: `dist`
+
+The path to the distribution directory. This is where the bundle file will be
+written to, if the `bundle` option is not specified.
+
+##### `cliOptions.eval`
+
+- Type: `boolean`
+- Default: `true`
+
+Whether to evaluate the bundle. If `true`, the bundle will be evaluated in the
+MetaMask Snaps runtime, to check for any compatibility issues.
+
+##### `cliOptions.manifest`
+
+- Type: `boolean`
+- Default: `true`
+
+Whether to validate the snap manifest. If `true`, the snap manifest will be
+validated, and any errors or warnings will be shown.
+
+##### `cliOptions.outfileName`
+
+- Type: `string`
+- Default: `bundle.js`
+
+The name of the bundle file. This is used to generate the bundle file path,
+using the `dist` option. For example, if `dist` is `dist`, and `outfileName`
+is `bundle.js`, the bundle file path will be `dist/bundle.js`. This option is
+ignored if the `bundle` option is specified.
+
+##### `cliOptions.port`
+
+- Type: `number`
+- Default: `8081`
+
+The port to use for the development server.
+
+##### `cliOptions.root`
+
+- Type: `string`
+- Default: `.`
+
+The root directory. This should be the directory that contains the snap
+manifest, and the `dist` directory. This will be served by the development
+server.
+
+##### `cliOptions.sourceMaps`
+
+- Type: `boolean`
+- Default: `false`
+
+Whether to generate source maps. If `true`, source maps will be generated for
+the bundle.
+
+##### `cliOptions.src`
+
+- Type: `string`
+- Default: `src/index.js`
+
+The path to the entry file. This is the file that will be bundled.
+
+##### `cliOptions.stripComments`
+
+- Type: `boolean`
+- Default: `true`
+
+Whether to strip comments from the bundle. If `true`, comments will be stripped
+from the bundle, and the bundle will be minified.
+
+##### `cliOptions.transpilationMode`
+
+- Type: `'localAndDeps' | 'localOnly' | 'none'`
+- Default: `'localOnly'`
+
+The transpilation mode to use. This determines which files will be transpiled
+by Babel. The possible values are:
+
+- `'localAndDeps'`: Transpile all files, including dependencies.
+- `'localOnly'`: Transpile only local files.
+- `'none'`: Do not transpile any files.
+
+##### `cliOptions.depsToTranspile`
+
+- Type: `string[]`
+- Default: `[]`
+
+If `transpilationMode` is `'localAndDeps'`, this option can be used to specify
+which dependencies should be transpiled. This is useful if you want to transpile
+a limited set of dependencies, but not all of them.
+
+##### `cliOptions.writeManifest`
+
+- Type: `boolean`
+- Default: `true`
+
+Whether to write the snap manifest. If `true`, the snap manifest will be written
+with any changes made by the CLI, if the manifest is invalid.
+
+##### `cliOptions.serve`
+
+- Type: `boolean`
+- Default: `true`
+
+Whether to serve the snap. If `true`, the snap will be served by the development
+server, when running `mm-snap watch`.
+
+##### `cliOptions.suppressWarnings`
+
+- Type: `boolean`
+- Default: `false`
+
+This option exists for backwards compatibility, and is ignored.
+
+##### `cliOptions.verboseErrors`
+
+- Type: `boolean`
+- Default: `false`
+
+This option exists for backwards compatibility, and is ignored.
+
+#### `bundlerCustomizer`
+
+- Type: `(bundler: BrowserifyObject) => void`
+
+A function that customizes the bundler. This function is called after the
+bundler is created, but before the bundle is written to disk. This can be used
+to customize the bundler, for example to add plugins or transforms.
+
+```typescript
+import type { SnapConfig } from '@metamask/snaps-cli';
+import type { BrowserifyObject } from 'browserify';
+
+const config: SnapConfig = {
+  bundlerCustomizer: (bundler: BrowserifyObject) => {
+    // Add the BRFS transform to Browserify.
+    bundler.transform('brfs');
+  },
+};
+
+export default config;
+```