|
| 1 | +# AGENTS.md |
| 2 | + |
| 3 | +`motoko` is a TypeScript library that compiles and runs Motoko smart contracts in Node.js or the browser, wrapping the bundled `moc` compiler. |
| 4 | + |
| 5 | +## Commands |
| 6 | + |
| 7 | +- Build: `npm run build` (cleans `lib/` then runs `tsc -p .`). |
| 8 | +- Test: `npm test` (Jest via `ts-jest`). |
| 9 | +- Format: `prettier --write` (run automatically on staged files by the pre-commit hook). |
| 10 | +- Size check: `npm run size-limit`. |
| 11 | +- Regenerate bundled compiler artifacts: `npm run generate <moc_version> <core_version>` (running with no args prints the latest available versions instead). |
| 12 | + |
| 13 | +There is no separate lint step; formatting is enforced by Prettier. |
| 14 | + |
| 15 | +## Layout |
| 16 | + |
| 17 | +- `src/` — TypeScript source; the published entry points (`index.js`, `interpreter.js`) re-export from the compiled `lib/`. |
| 18 | +- `utils/generate.js` — script that downloads and writes the bundled compiler/package artifacts. |
| 19 | +- `contrib/` — extra integrations (syntax highlighting, snippets); `contrib/generated/` is produced by `generate`. |
| 20 | +- `versions/` — bundled minified `moc` builds; `versions/latest/` is generated. |
| 21 | +- `packages/` — bundled Motoko package data; `packages/latest/` is generated. |
| 22 | +- `tests/` — Jest test suites. |
| 23 | +- `examples/` — runnable usage examples. |
| 24 | + |
| 25 | +## Conventions & gotchas |
| 26 | + |
| 27 | +- Never hand-edit generated outputs: `lib/` (build output, gitignored), `versions/latest/`, `packages/latest/`, and `contrib/generated/`. Change `src/` or `utils/generate.js` and rebuild/regenerate instead. |
| 28 | +- Prettier config: 4-space indent, single quotes, semicolons, trailing commas (`.prettierrc`). `lib/generated` is excluded from formatting. |
| 29 | +- A Husky pre-commit hook runs `lint-staged`, which formats staged files under `lib/`, `contrib/`, and `utils/`. |
| 30 | +- `.npmrc` sets `min-release-age=7`, delaying installs of dependency versions newer than 7 days. |
| 31 | +- CI tests run on Node 22 and 24; build and publish jobs use Node 24. Use a supported Node version locally. |
| 32 | +- Publishing is automated: pushing a changed `version` in `package.json` to `main` triggers an npm publish. |
0 commit comments