virmator

A package for centralizing and automating mind-numbingly repetitive repo tasks and checks. New commands can easily be added through a plugin system.

Note that as of v13, this package is now in ESM.

virmator usage

[npx] virmator [--flags] command subCommand [...optional args]

• npx is needed when the command is run directly from the terminal (not called from within an npm script) unless virmator has been globally installed (which I recommend against).
• [--flags] is any of the optional virmator flags. See Virmator Flags below.
• command, subCommand, and [...optional args] depend on the specific command you're running. See Available Commands below.

Available commands

• compile

  Type checks TypeScript files and compiles them into JS outputs using the TypeScript compiler. Any extra args are passed directly to tsc.

  Automatically compiles a mono-repo's sub packages in the correct order if called from a mono-repo root.

  • Examples
    • virmator compile
    • With tsc flags: virmator compile --noEmit
  • Configs
    • tsconfig.json
    • configs/tsconfig.base.json
  • Deps
    • typescript
    • mono-vir

• deps

  Various dependency commands. A sub-command must be provided.

  • Examples

    • check import dependencies: virmator deps check
    • upgrade npm dependencies: virmator deps upgrade
    • regenerate npm dependencies: virmator deps regen

  • Sub Commands

    • check

      Checks that import dependencies pass your dependency cruiser config. The base configuration blocks typical import errors such as circular dependencies and importing test files.

      • Examples
        • virmator deps check
      • Configs
        • configs/dep-cruiser.config.cts
      • Deps
        • dependency-cruiser
        • esbuild

    • upgrade

      Upgrades dependencies using npm-check-update. Does not automatically run 'npm i'. It is recommended to run 'virmator deps regen' instead.

      • Examples
        • virmator deps upgrade
      • Configs
        • configs/ncu.config.ts
      • Deps
        • npm-check-updates

    • regen

      Force regeneration of all all dependencies by deleting all node_modules directories and package-lock.json and then running 'npm i'.

      • Examples
        • virmator deps regen

• docs

  Generates documentation using the typedoc package and inserts code examples into README files using the markdown-code-example-inserter package.

  • Examples

    • virmator docs

  • Configs

    • configs/typedoc.config.ts

  • Deps

    • markdown-code-example-inserter
    • typedoc

  • Sub Commands

    • check

      Checks that documentation is valid and passes all checks without generating documentation outputs.

      • Examples
        • virmator docs check

• format

  Formats with prettier.

  • Examples

    • virmator format

  • Configs

    • prettier.config.mjs
    • .prettierignore

  • Deps

    • prettier
    • prettier-plugin-jsdoc
    • prettier-plugin-multiline-arrays
    • prettier-plugin-organize-imports
    • prettier-plugin-packagejson
    • prettier-plugin-sort-json
    • prettier-plugin-toml
    • prettier-plugin-interpolated-html-tags

  • Sub Commands

    • check

      Checks that formatting is all valid.

      • Examples
        • virmator format check

• frontend

  Runs a frontend dev server with Vite.

  • Examples

    • virmator frontend

  • Configs

    • configs/vite.config.ts

  • Deps

    • typescript
    • vite

  • Sub Commands

    • build

      Builds a frontend for deployment using Vite (and Rollup).

      • Examples
        • virmator frontend build

    • preview

      Builds a frontend and previews that build in a local dev server.

      • Examples
        • virmator frontend preview

• help

  Prints help messages for all supported plugins/commands.

  • Examples
    • virmator help

• init

  Init all default configs. Needs env and package type args.

  • Examples
    • virmator init web mono-repo
    • virmator init node package
  • Configs
    • .github/workflows/build-for-gh-pages.yml
    • .github/workflows/tagged-release.yml
    • .github/workflows/tests.yml
    • .vscode/settings.json
    • src/ui/elements/vir-app.element.ts
    • src/index.html
    • www-static/index.css
    • www-static/_redirects
    • .gitattributes
    • .nvmrc
    • .gitignore
    • LICENSE-MIT
    • LICENSE-CC0
    • .npmignore
    • package.json

• lint

  Runs ESLint.

  • Examples

    • virmator lint

  • Configs

    • configs/tsconfig.eslint.json
    • eslint.config.mjs

  • Deps

    • eslint
    • eslint-plugin-require-extensions
    • eslint-plugin-unicorn
    • @eslint/js
    • @eslint/eslintrc
    • @stylistic/eslint-plugin
    • eslint-plugin-monorepo-cop
    • @stylistic/eslint-plugin-ts
    • @typescript-eslint/eslint-plugin
    • eslint-config-prettier
    • eslint-plugin-jsdoc
    • eslint-plugin-playwright
    • eslint-plugin-prettier
    • eslint-plugin-sonarjs
    • typescript-eslint

  • Sub Commands

    • fix

      Auto fix all fixable ESLint issues.

      • Examples
        • virmator lint fix

• publish

  Publish a package or mono-repo to NPM with an optional test script and auto-incrementing package version.

  • Examples
    • With tests: virmator publish npm test
    • Without tests: virmator publish

• spellcheck

  Checks spelling for all files using the cspell package. All arguments are passed directly to cspell.

  • Examples
    • virmator spellcheck
    • Check a specific file: virmator spellcheck src/index.ts
  • Configs
    • cspell.config.cjs
  • Deps
    • cspell

• test

  Runs tests. An environment is required.

  This cannot be run in a mono-repo root, it can only be run for mono-repo sub-packages or a top-level singular package.

  • Examples

    • Run tests in a browser: virmator test web
    • Run tests in Node: virmator test node

  • Deps

    • @augment-vir/test
    • @augment-vir/assert

  • Sub Commands

    • web

      Runs web tests in a browser using web-test-runner.

      • Examples

        • virmator test web

      • Configs

        • configs/web-test-runner.config.mjs

      • Deps

        • @web/dev-server-esbuild
        • @web/test-runner-commands
        • @web/test-runner-playwright
        • @web/test-runner-visual-regression
        • @web/test-runner
        • istanbul-smart-text-reporter

      • Sub Commands

        • coverage

          Run tests and calculate code coverage.

          • Examples
            • virmator test web coverage

        • update

          Run tests and update snapshots.

          • Examples
            • virmator test web update

    • node

      Runs backend tests in Node.js using its built-in test runner.

      • Examples

        • virmator test node

      • Sub Commands

        • coverage

          Run tests and calculate code coverage.

          • Examples
            • virmator test node coverage
          • Configs
            • configs/c8.config.json
          • Deps
            • c8
            • istanbul-smart-text-reporter
            • @types/node

        • update

          Run tests and update snapshots.

          • Examples
            • virmator test node update

Virmator Flags

All virmator flags are optional and typically not needed.

• --no-configs: Prevents command config files from being copied.
• --no-deps: Prevents command npm deps from being installed.
• --help: Print the help message.