{"id":17655819,"url":"https://github.com/lume/cli","last_synced_at":"2025-05-07T11:13:51.217Z","repository":{"id":54368539,"uuid":"120862086","full_name":"lume/cli","owner":"lume","description":"A CLI for managing TypeScript packages.","archived":false,"fork":false,"pushed_at":"2023-11-22T03:01:31.000Z","size":288,"stargazers_count":5,"open_issues_count":13,"forks_count":2,"subscribers_count":8,"default_branch":"main","last_synced_at":"2024-04-14T09:04:33.473Z","etag":null,"topics":["automation","babel","builder","builder-archetype","builders","webdev","webpack"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lume.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2018-02-09T05:39:58.000Z","updated_at":"2023-06-18T02:23:43.000Z","dependencies_parsed_at":"2023-10-03T04:12:52.844Z","dependency_job_id":"92629066-ae58-4aed-8485-a9fbf349c646","html_url":"https://github.com/lume/cli","commit_stats":{"total_commits":297,"total_committers":2,"mean_commits":148.5,"dds":0.03367003367003363,"last_synced_commit":"56565bc3f435d0819f9e4e7f74622c72f09e6762"},"previous_names":[],"tags_count":68,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lume%2Fcli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lume%2Fcli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lume%2Fcli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lume%2Fcli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lume","download_url":"https://codeload.github.com/lume/cli/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242722979,"owners_count":20174995,"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":["automation","babel","builder","builder-archetype","builders","webdev","webpack"],"created_at":"2024-10-23T13:08:09.323Z","updated_at":"2025-03-11T00:32:38.308Z","avatar_url":"https://github.com/lume.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @lume/cli\n\nA command line tool for building, testing, and publishing JavaScript/TypeScript packages.\n\nWrite source code (with tests) and don't worry about the specifics of package\nmanagement.\n\n`@lume/cli` is designed with ES Modules (ESM), i.e. JavaScript modules, in mind. CommonJS is not supported.\n\n#### `npm install @lume/cli --global`\n\n## Current Features\n\nThe following is a brief overview of LUME cli's features. For more details,\nsee `lume --help`.\n\n- Build a project's [TypeScript](https://www.typescriptlang.org) source code\n  from its `src/` folder to a `dist/` output folder.\n  - The output code is in standard ES Module format.\n- Formats all code in a project with [`prettier`](https://prettier.io).\n- Run a project's tests (any files ending with `.test.ts` in the project's src/\n  folder) with the excellent\n  [`@web/test-runner`](https://modern-web.dev/docs/test-runner/overview/).\n  - Tests use [Mocha](https://mochajs.org)'s `describe()`/`it()` functions for describing unit tests.\n  - Tests use Jest's [`expect()`](https://jestjs.io/docs/expect) library for assertions (`expect` is global, don't `import` it, TODO: type definition for `expect()`)\n  - Tests run in Google Chrome (TODO: `@web/test-runner` has more browser launchers, expose more options).\n- Publish a project to NPM.\n\n## Future Features\n\n- Allow more configuration overrides (f.e. `@web/test-runner` options).\n- Scaffold LUME-based applications.\n- Scaffold LUME elements.\n- Scaffold generic packages.\n- Ensure full support of plain JavaScript (untested, as Lume packages are all\n  TypeScript, but if it doesn't already work, it probably requires minimal\n  changes)\n\n## Projects using LUME CLI\n\n[lume/element](https://github.com/lume/element),\n[classy-solid](https://github.com/lume/classy-solid),\n[lume/element-behaviors](https://github.com/lume/element-behaviors),\n[lume/lume](https://github.com/lume/lume),\n[trusktr/lowclass](https://github.com/trusktr/lowclass),\n[trusktr/perfect](https://github.com/trusktr/perfect)\n\nNotice in those projects that they have no dependencies on any build tools directly\nand no build configurations; they use `lume` commands for building, testing,\nformatting, and publishing in a common way.\n\n\u003e [!Note]\n\u003e This project initially meets needs for LUME packages, and as such may not\n\u003e be a perfect fit for everyone's needs.\n\u003e\n\u003e I'd like to make this easy to extend and even more generic to fit any needs, so that only few\n\u003e modifications are needed in order to adopt its use for more specific cases (f.e. adding Babel\n\u003e or `@web/test-runner` plugins). See [TODO](#todos).\n\n## Requirements\n\n- Linux or macOS if publishing commands will be used, otherwise any OS for all other commands.\n- One of the latest two LTS versions of Node.js (might work with lower versions, not tested)\n- One of the lataest two versions of NPM (might work with lower versions, not tested)\n\n## Getting Started\n\nThere are two ways to install LUME cli.\n\n### Local Install (recommended)\n\nInstall the cli as a dev dependency of your project, so you can rely on a\nspecific version of it with confidence.\n\n**`npm install @lume/cli --save-dev`**\n\nThen use the `npx` command (which ships with `npm` and is used to run local\nexecutables) to run the cli and show the help menu:\n\n**`npx lume --help`**\n\n### Global Install\n\nInstall the `lume` command globally so it is available in any shell:\n\n**`npm install @lume/cli --global`**\n\nIf the above fails with permissions errors, you may need to run it with `sudo` in Linux/macOS or Admin priviliges in Windows:\n\n**`sudo npm install @lume/cli --global`**\n\nThen run the cli and show the help menu:\n\n**`lume --help`**\n\n\u003e [!Important]\n\u003e Installing `lume` globally may work up to a certain point (at least\n\u003e the way the cli currently works, where it does not yet manage internal\n\u003e versioning). If you have multiple projects that depend on different versions\n\u003e of the `lume` cli with differing and incompatible features, you'll want to\n\u003e install specific versions locally in each project instead. In the future,\n\u003e the LUME cli will have internal version management.\n\n### No Install (easiest)\n\nUsing `npx`, we can also skip installing the LUME cli at all. If `npx` does\nnot detect a locally-installed version of an executable in a project, it will\ndefault to downloading the latest version of the executable and running it.\n\nUse the `npx` command (which ships with `npm` and is used to run local\nexecutables) to run the cli and show the help menu:\n\n**`npx lume --help`**\n\n\u003e [!Important]\n\u003e This poses a problem similar to the global install option: the latest\n\u003e version of the cli downloaded by `npx` may not be the version of LUME cli\n\u003e that your project works with. In the future, the LUME cli may have internal\n\u003e version management.\n\n## Project setup\n\n### File structure\n\nThe general structure of a project mananaged with the `lume` cli is as follows:\n\n```sh\nsrc/               # All source files go here, as well as `.test.ts` files.\n  index.ts         # The project's entry point.\n  index.test.ts    # A co-located test file.\n  ...              # Other files imported by entry point, and associated test files.\ndist/              # The folder where build output goes (you might ignore this folder in your version control system).\n.gitignore         # Things to ignore, like the `dist/` output folder, are listed in here.\npackage.json       # The project meta file, listing dependencies, scripts, etc.\nlume.config.cjs    # Optional config options read by `lume` cli, see below.\ntsconfig.json      # Optional, TypeScript configuration overrides. Extend from ./node_modules/@lume/cli/config/ts.config.json.\n```\n\nThe `lume build` command will compile `.ts` files from the `src/` folder,\noutputting them as `.js` files along with `.js.map` [source map\nfiles](https://developer.mozilla.org/en-US/docs/Tools/Debugger/How_to/Use_a_source_map)\ninto the `dist/` folder. It will also output `.d.ts` and `.d.ts.map` files for\ntype definitions and mapping from type definitions back to `.ts` sources files.\n\n### Set up files\n\nLet's set up `package.json`, `.gitignore`, `src/index.ts`, and `src/index.test.ts`.\n\n\u003e NOTE, in the near future we'll add command to LUME cli to scaffold these\n\u003e files.\n\nWe'll want to have the following things in our `package.json` (not all\n`scripts` are required, but this makes them convenient to call with `npm run`\nand documents their existence to anyone looking in `package.json` to\nunderstand available actions).\n\n**`package.json`**\n\n```json\n{\n\t\"name\": \"PACKAGE-NAME\",\n\t\"version\": \"0.0.0\",\n\t\"license\": \"MIT\",\n\t\"type\": \"module\",\n\t\"main\": \"dist/index.js\",\n\t\"types\": \"src/index.ts\",\n\t\"exports COMMENT:\": \"This removes 'dist' from import statements, as well as replaces the 'main' field. See https://github.com/nodejs/node/issues/14970#issuecomment-571887546\",\n\t\"exports\": {\n\t\t\".\": \"./dist/index.js\",\n\t\t\"./\": \"./dist/\"\n\t},\n\t\"scripts\": {\n\t\t\"clean\": \"lume clean\",\n\t\t\"build\": \"lume build\",\n\t\t\"dev\": \"lume dev\",\n\t\t\"typecheck\": \"lume typecheck\",\n\t\t\"typecheck:watch\": \"lume typecheckWatch\",\n\t\t\"test\": \"lume test\",\n\t\t\"test:debug\": \"lume testDebug\",\n\t\t\"prettier\": \"lume prettier\",\n\t\t\"prettier:check\": \"lume prettierCheck\",\n\t\t\"release:patch\": \"lume releasePatch\",\n\t\t\"release:minor\": \"lume releaseMinor\",\n\t\t\"release:major\": \"lume releaseMajor\",\n\t\t\"version\": \"lume versionHook\",\n\t\t\"postversion\": \"lume postVersionHook\",\n\t\t\"prepare\": \"npm run build\"\n\t}\n}\n```\n\nWhere `PACKAGE-NAME` would be the actual name of our package.\n\nWe should ignore some things in a `.gitignore` file.\n\n**`.gitignore`**\n\n```sh\nnode_modules/ # project dependencies\ndist/ # build output (unless you want to commit output JS files)\n*.log # log files in case of errors, etc\n```\n\nLastly, let's create `src/index.ts` with some sample code and ensure that it\nexports the project's version number at the very bottom:\n\n**`src/index.ts`**\n\n```ts\nexport function isAwesome(thing: string) {\n\treturn `${thing} is awesome.`\n}\n\nexport const version = '0.0.0'\n```\n\nThe `lume release*` commands will automatically update both the exported\n`version` variable in `src/index.ts` and the `version` field in\n`package.json`.\n\n\u003e NOTE! At the moment the release commands will throw an error if they don't\n\u003e find this line at the bottom of the entrypoint. We'll make this optional in\n\u003e the near future.\n\nLets write a test file to test our nifty `isAwesome` function.\n\n**`src/index.test.ts`**\n\n```ts\nimport {isAwesome} from './index.js'\n\ndescribe('isAwesome', () =\u003e {\n\tit('is a function', () =\u003e {\n\t\texpect(isAwesome).toBeInstanceOf(Function)\n\t})\n\n\tit('says things are awesome', () =\u003e {\n\t\texpect(isAwesome('Code')).toBe('Code is awesome.')\n\t})\n})\n```\n\nThis is enough to get a project bootstrapped. To learn more on how to\nconfigure build and test settings with `lume.config.cjs` and `tsconfig.json`\nfiles, see [Configuration](#configuration) below.\n\n## Configuration\n\nThe `lume.config.cjs` and `tsconfig.json` files can be used for\nconfiguration.\n\n**`lume.config.cjs`**\n\nVarious parts of the build/test/publish process can be configured with a\n`lume.config.cjs` file at the root of the project. The following example\nshows the available options with their defaults.\n\n```js\nmodule.exports = {\n\t// EXPERIMENTAL\n\t// Whether or not to run the TypeScript compiler in project reference mode\n\t// (--build) for incremental compilation. This requires some advanced\n\t// configuration of tsconfig.json.\n\t//\n\t// Default: false\n\ttsProjectReferenceMode: true,\n\n\t// The figlet font to use when your project's name is displayed at the\n\t// beginning of `lume build`. Info: https://www.npmjs.com/package/figlet\n\t//\n\t// Example:\n\t//   _   _      _ _        __        __         _     _ _ _\n\t//  | | | | ___| | | ___   \\ \\      / /__  _ __| | __| | | |\n\t//  | |_| |/ _ \\ | |/ _ \\   \\ \\ /\\ / / _ \\| '__| |/ _` | | |\n\t//  |  _  |  __/ | | (_) |   \\ V  V / (_) | |  | | (_| |_|_|\n\t//  |_| |_|\\___|_|_|\\___/     \\_/\\_/ \\___/|_|  |_|\\__,_(_|_)\n\t//\n\t// Default: 'ICL-1900'\n\tfigletFont: 'Ghost',\n\n\t// If true, transpile TypeScript code with Babel instead of TypeScript. The\n\t// `tsc` command will be used only for type checking, while the actual code\n\t// transpilation will be done with `babel`.\n\t//\n\t// This can be useful, for example, when TypeScript doesn't support a feature\n\t// Babel does. For example, at the time of writing this, Babel had Stage 3\n\t// decorators, while TypeScript did not.\n\t//\n\t// NOTE! If you do not use this option, the legacy version of decorators will\n\t// be used. This option must be `true` if you wish to use the current\n\t// decorator spec.\n\t//\n\t// Default: true\n\tuseBabelForTypeScript: false,\n\n\t// A path (if not absolute, then relative to the working directory) to a file\n\t// that has ignore rules in it. This is useful for cases when we want `lume\n\t// prettier` to use a specific ignore file, but otherwise (for example) want\n\t// our IDE to use the default .prettierignore file. In the `lume` repo, we\n\t// want the IDE to format on save in any file we are editing, even in\n\t// sub-workspaces, but we want `lume prettier` to format only files in the top\n\t// level workspace.\n\t//\n\t// Default: The `.prettierignore` in your project if it exists, otherwise \"./node_modules/@lume/cli/.prettierignore\".\n\tprettierIgnorePath: './path/to/.some-other-ignore-file',\n\n\t// The test files that will be executed with `@web/test-runner`. It can be a\n\t// string glob, or array of string globs. Prefix a glob with `!` to negate\n\t// it.\n\t//\n\t// Default: \"dist/**/*.test.js\"\n\ttestFiles: ['./build/**/tests/*.js'],\n\n\t// The import map to use for `@web/test-runner`, which runs tests as native\n\t// JavaScript modules in a browser. The import map is needed for mapping\n\t// import specifiers to URLs from which to get those imports. Learn about import maps here:\n\t// https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap\n\t//\n\t// Default: {}\n\timportMap: {\n\t\timports: {\n\t\t\t// If we `npm install`ed `some-package`, then we tell web test-runner where to get it from:\n\t\t\t'some-package': '/node_modules/some-package/dist/index.js',\n\t\t},\n\t},\n}\n```\n\n**`tsconfig.json`**\n\nTo configure (override) TypeScript compiler options, create a `tsconfig.json`\nfile at the root of the project that extends from\n`./node_modules/@lume/cli/config/ts.config.json`, and override any settings\nas needed (to see what LUME cli's default settings are, see\n[./config/ts.config.ts](./config/ts.config.json)).\n\n\u003e [!Note]\n\u003e If you don't wish to override anything, then `tsconfig.json` is not necessary,\n\u003e Lume cli will automatically use its own config during `lume build`. However,\n\u003e IDEs by default look for `tsconfig.json` for configuration, so if you want your\n\u003e IDE to use the same configuration, you can make an empty config that only\n\u003e `extends` from Lume's.\n\nSee the [TypeScript compiler\noptions](https://www.typescriptlang.org/docs/handbook/compiler-options.html)\nFor TypeScript-specific build and type-checking configuration.\n\n```jsonc\n{\n\t\"extends\": \"./node_modules/@lume/cli/config/ts.config.json\",\n\t\"compilerOptions\": {\n\t\t\"target\": \"es5\"\n\t}\n}\n```\n\n## Managing a project\n\nNow that we've bootstrapped our project, the following are the basic commands\nwe'll want to run to manage the life cycle of our project.\nFor sake of\nsimplicity, the following examples assume that `lume` was installed globally\nas per the \"Global Install\" option above.\n\n- `lume dev`\n  - \"dev\" for \"development mode\"\n  - Builds all code, and rebuilds it automatically if any file changes.\n  - This is useful while developing a project, so that any time we edit\n    files, the project will automatically rebuild.\n- `lume prettierCheck`\n  - Check that files are formatted well.\n  - Exits with a non-zero error code if any files don't pass, showing failed files in the output.\n- `lume prettier`\n  - Format all files.\n- `lume test`\n  - Run tests (all `.test.js` files in `dist/`). Run `lume build` first if you are not already running `lume dev`.\n  - Exits with a non-zero error code if any test fails, showing failed tests in the output.\n- `lume test --watch`\n  - Run tests in watch mode. This is useful while running `lume dev` so that\n    tests automatically re-run as soon as `dist/` is updated.\n- `lume build`\n  - Does a production build, and does not watch for file changes.\n  - Currently this doesn't do anything except _not watch_ files to rebuild on\n    file changes. In the future, we might decide to minify output modules, etc.\n- `lume releasePatch`, `lume releaseMinor`, `lume releaseMajor`, etc\n  - Updates the version of the project in `package.json` and `src/index.ts`.\n  - It runs `lume clean \u0026\u0026 lume build \u0026\u0026 lume test` to ensure code is in\n    working condition.\n  - Publishes the project to NPM using the new version number only if build and\n    tests pass.\n  - Pushes a version commit and tag to the remote git repo, including updated\n    `dist/` which exports the new version number in `dist/index.js`.\n\nFor more commands and details, run `lume --help`.\n\n## Caveats\n\nThis uses TypeScript for transpiling all code. To customize build options,\nyou will need to get familiar with TypeScript's [compiler\noptions](https://www.typescriptlang.org/docs/handbook/compiler-options.html).\n\nIf you lower TypeScript's compiler `target` to ES5 or lower, you may need to\nenable the `downlevelIteration` option if you need spec-compliant for..of\nloops (for example if you depend on in-place modification of iterables like\nSet while iterating on them, etc).\n\n## TODOs\n\n- [ ] Add support for JSX (specifically Solid JSX expressions which requires Babel).\n- [ ] Allow overriding of Babel config.\n- [x] Source maps! Important!\n- [x] Important! Don't run `git stash` during version script if there's nothing to stash,\n      otherwise it will pop a previous stash after `npm version` is done.\n- [ ] Ability to scaffold applications.\n- [ ] Ability to scaffold packages.\n- [x] Testing (we're using `@web/test-runner`)\n- [ ] Code coverage (configure web test-runner, https://modern-web.dev/docs/test-runner/writing-tests/code-coverage/)\n- [ ] Enable visual regression testing (https://github.com/modernweb-dev/web/tree/master/packages/test-runner-visual-regression)\n- [ ] Switch to a separate `src/version.ts` file for the version number\n      export. Skip updating it if it doesn't exist instead of crashing.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flume%2Fcli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flume%2Fcli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flume%2Fcli/lists"}