{"id":16682650,"url":"https://github.com/jchip/module-dev","last_synced_at":"2025-12-26T21:19:39.495Z","repository":{"id":204187624,"uuid":"711248931","full_name":"jchip/module-dev","owner":"jchip","description":null,"archived":false,"fork":false,"pushed_at":"2023-10-28T19:50:22.000Z","size":309,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-01-20T07:26:06.770Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jchip.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2023-10-28T16:54:16.000Z","updated_at":"2023-10-28T16:54:37.000Z","dependencies_parsed_at":null,"dependency_job_id":"74c9bc82-7f5a-4b22-a7ce-4b9ffcbcb495","html_url":"https://github.com/jchip/module-dev","commit_stats":null,"previous_names":["jchip/module-dev"],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jchip%2Fmodule-dev","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jchip%2Fmodule-dev/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jchip%2Fmodule-dev/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jchip%2Fmodule-dev/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jchip","download_url":"https://codeload.github.com/jchip/module-dev/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243392326,"owners_count":20283565,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-12T14:08:09.800Z","updated_at":"2025-12-26T21:19:34.468Z","avatar_url":"https://github.com/jchip.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# node.js modules development support\n\nThis module offers common config and setup for developing a node.js module.\n\nSupport for standard tools include:\n\n- Language: [TypeScript]\n- Testing and code coverage: [chai], [mocha], [nyc], [sinon], [tap], [jest]\n- Code linting: [eslint]\n- Documentation: [jsdoc], [typedoc]\n\n## Installation\n\nTo start a new module, first create the directory for it:\n\n```sh\nmkdir my-module\ncd my-module\n```\n\nThen follow the instructions below to setup development:\n\n1. Within your new project dir, run:\n\n```sh\nnpm init --yes\nnpm install --save-dev @xarc/module-dev\n```\n\n2. Bootstrap: then to bootstrap your project, use the following commands:\n\n```sh\nnpx xrun --require @xarc/module-dev init\nnpm install\n```\n\n- `init` takes the following options. ie: `npx xrun --require @xarc/module-dev init --eslint`\n\n  - `--no-typescript` - bootstrap without typescript support.\n  - `--eslint` - bootstrap with eslint support.\n\n3. Now you can run `npx xrun` to see a list of build tasks available for developing your node.js module.\n\n### @xarc/run-cli\n\nIf you want to be able to run `xrun` directly instead of having to do `npx xrun`, then you can install globally a simple package [@xarc/run-cli] with the following command.\n\n```sh\n$ npm install -g @xarc/run-cli\n```\n\n## Project Structure\n\nThis module's setup assumes your project follows a directory structure like below:\n\n```\n.gitignore\npackage.json\ntsconfig.json\n\nlib/\n  index.js\n\ndist/\n  index.js\n  index.d.js\n  index.js.map\n\nsrc/\n  index.ts\n\ntest/\n  spec/**\n    *.spec.js\n    *.spec.ts\n```\n\nIf you are writing JavaScript that node.js can execute directly, then you can put them in `lib` dir.\n\nIf you are using TypeScript, then you can put your `ts` source in `src` dir, and then run `npx tsc` to compile them into the `dist` dir.\n\n`.d.ts` type definition files and source map files will also be generated into the `dist` dir.\n\n## Developing\n\nOnce you start writing your code, either as [TypeScript] in `src` or JavaScript in `lib`, you should put your tests in the directory `test/spec` as `*.spec.js` or `*.spec.ts` files.\n\nThe following are common build tasks that you would use:\n\n- Run linting and tests: `npx xrun test`\n- Run tests without linting: `npx xrun test-only`\n- Run linting and tests with coverage: `npx xrun check`\n\nYour [TypeScript] tests should import your TS code from `src` directly.\n\n## Publishing\n\nWhen you are ready to publish your module to [npm], please keep the following in mind:\n\nThis module automatically setup [files] in your `package.json` to include these files to publish:\n\n- `lib` - If you have JavaScript in `lib` dir\n- `dist` - If you are writing your code in [TypeScript].\n\nFor [TypeScript], your code from `src` directory is not included. If you want to include `src` dir, please add that to [files].\n\n- If you have any other files or dirs that you want to publish, then add them to the `files` list.\n- You can run `npm publish --dry-run` to see what [npm] will do without actually publishing for real.\n- When you are ready to publish for real, you can run `npm publish`.\n\n## [TypeScript] Support\n\nIf you boostrapped your project without [TypeScript], but then want to add it later, you can run the `typescript` build task any time:\n\n```sh\nnpx xrun typescript\nnpm install\nmkdir src\n```\n\nAnd now you can start writing typescript code in the `src` directory\n\n### tsconfig.json\n\nAfter this module created `tsconfig.json` for you, you can change it as you like. This module won't override your settings.\n\n#### `esModuleInterop`\n\nThe default `tsconfig.json` will set `esModuleInterop` to `true` for you so you can import classic modules directly\nlike `import Path from \"path\"`. Set it to `false` if you don't want this.\n\n#### `tslib` and `importHelpers`\n\n`tslib` is automatically added to your module's `dependencies` and `importHelpers` set to `true` in your `tsconfig.json`. If this is not needed or wanted, then feel free to remove them. They won't be touched again.\n\n## [eslint] Support\n\nIf you didn't bootstrap your project with [eslint] support, you can always add it later by running `npx xrun eslint`, and then `npm install`.\n\nYou need to create a `.eslintrc.js` file. If you want to use the eslint config this module setup, set it to:\n\n```js\nconst { eslintRcNodeTypeScript } = require(\".\");\nmodule.exports = {\n  extends: eslintRcNodeTypeScript,\n};\n```\n\nThe configs available are:\n\n- `eslintRcNode` - Node.js\n- `eslintRcNodeTypeScript` - Node.js for typescript\n- `eslintRcTest` - Unit test code\n- `eslintRcTestTypeScript` - typescript unit test code\n\nYou can invoke the linting task with `npx xrun lint`\n\nThe build task `check` will run linting also. You can invoke it with `npx xrun check`.\n\nIf you need to disable certain eslint rules for a specific source file, you can add the following comment to the top of your file.\n\n```js\n/* eslint-disable no-console, no-magic-numbers, max-statements */\n```\n\nThis comment disables the following three rules:\n\n- `no-console`\n- `no-magic-numbers`\n- `max-statements`\n\n## [jsdoc] linting\n\nIf you've enabled [eslint], then linting rules for [jsdoc] is added with the plugin [eslint-plugin-jsdoc].\n\n## [typedoc] Support\n\nIf you've enabled [TypeScript], then [typedoc] is added to automatically generate HTML in `docs` from your [jsdoc] in your code in the `src` directory.\n\nTo generate the docs manually, run `npm run docs`. And then open `docs/index.html` to see the generated HTML docs.\n\n### Fix [typedoc] externals\n\n[typedoc] treats every filenames as a module and that doesn't work well with the practice of one class per file.\n\nTo customize modules for [typedoc], install the module `typedoc-plugin-external-module-name`.\n\nThen in the `.ts` files:\n\n- Use the following command to assign a file to a module.\n\n```js\n/**\n * @packageDocumentation\n * @module index\n */\n```\n\n- Use the following command to ignore a file:\n\n```js\n/** @ignore */ /** */\n```\n\n- Use the following command before any `export` to ignore it.\n\n```js\n/** @ignore */\nexport function internallySharedFunction() {}\n```\n\n## Compiling JSX\n\nYou can add JSX support by updating your `tsconfig.json` with following options:\n\n```js\n{\n  compilerOptions: {\n    \"jsx\": \"react\"\n  }\n}\n```\n\n### React\n\n- To compile React JSX components:\n\n1. Add [react] to your dependencies: `npm install react`\n\n### Preact\n\n- To compile Preact JSX components:\n\n1. Add [preact] to your dependencies: `npm install preact`\n2. Update `compilerOptions` in `tsconfig.json`:\n\n```js\n{\n  \"compilerOptions\": {\n    \"lib\": [\"dom\"],\n    \"jsxFactory\": \"h\"\n  }\n}\n```\n\n## Additional Targets\n\nIf you need to compile your `src` to multiple targets, you can do this by:\n\n1. Make a copy of `tsconfig.json` for your target. ie: `tsconfig.es5.json`\n2. Add a `npm scripts` to run `tsc` with `--build` option. ie: `tsc --build tsconfig.es5.json`\n3. Update `build` script to have `xrun` run your new compile script. So if you named it `compile.es5`, your `build` would be: `xrun -n compile compile.es5`\n\n- In your additional target config, you don't need `tsc` to generate the `.d.ts` files. You can turn it off by setting `declaration` to `false`\n\n## License\n\nLicensed under the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0)\n\n---\n\n[@xarc/run-cli]: https://www.npmjs.com/package/@xarc/run-cli\n[typescript]: https://www.typescriptlang.org/\n[eslint]: https://eslint.org/\n[mocha]: https://mochajs.org/\n[chai]: https://www.chaijs.com/\n[nyc]: https://istanbul.js.org/\n[sinon]: https://sinonjs.org/\n[jsdoc]: https://jsdoc.app/\n[typedoc]: https://typedoc.org/\n[eslint-plugin-jsdoc]: https://www.npmjs.com/package/eslint-plugin-jsdoc\n[files]: https://docs.npmjs.com/files/package.json#files\n[npm]: https://www.npmjs.com/\n[react]: https://reactjs.org/\n[preact]: https://preactjs.com/\n[tap]: https://www.npmjs.com/package/tap\n[jest]: https://jestjs.io/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjchip%2Fmodule-dev","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjchip%2Fmodule-dev","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjchip%2Fmodule-dev/lists"}