Helper packages for JS/TS repositories
Interested in development? Join the discussion on the Eterna Discord!
Want to set up a new repository using Eterna's standard structure? Check out @eternagame/bootstrap
This will also set you up to use our Nx plugin, @eternagame/nx-plugin, which has our standard Nx
configuration and package generators.
@eternagame/tsconfig- Eterna standard TypeScript configurations@eternagame/eslint-plugin- Eterna standard ESLint setup and utilities@eternagame/vite-utils- Eterna standard Vite setup and utilities@eternagame/lint-staged-utils- Eterna standard lint-staged setup and utilities@eternagame/cypress-utils- Eterna standard Cypress setup and utilities
@eternagame/nx-spawn- Run an npm command with Nx dependencies without waiting for them to finish
- Install NodeJS (we recommend using the latest LTS version)
- Run
npm installin the root of this repository
This repository is structured as a monorepo, using NPM Workspaces and Nx to manage its components. Here are some common actions you might want to take:
Run npx nx dev <package-name> to run an application package, automatically reloading when changes occur.
Run npx nx start <package-name> to run after building the package (with dependencies) without reloading.
Run npx nx build <package-name> to build a package. This will also build any dependencies of the package.
Run npx nx build:watch <package-name> to build a package and rebuild when files are changed.
This will also build any dependencies of the package.
Run npx nx lint <package-name> to run linting for a package via ESLint.
Run npx nx lint <package-name> --fix to run linting with automatic fixes
Run npx nx test <package-name> to execute unit/component tests for a package via Vitest
or Cypress (depending on which is configured for the package).
Run npx nx test:watch <package-name> to execute unit/component tests for a package in watch mode (Vitest only).
Run npx nx test:cov <package-name> to execute unit/component tests and report code coverage for a
package in watch mode (Vitest only).
Run npx nx test:ui <package-name> to execute unit/component tests for a package using the UI-based test runner (Cypress only).
Run npx nx affected:test to execute unit/component tests for all packages affected by a code change.
Run npx nx e2e <package-name> to execute end to end tests in a package, if configured.
Run npx nx affected:e2e to execute all end to end tests in packages affected by a code change.
You can use the Eterna Nx plugin to automatically create and update files, including adding new packages.
To see the available generators, run npx nx list @eternagame/nx-plugin. To run a given generator,
run npx nx generate <generator> (eg, npx nx generate ts-iso). Running npx nx generate <generator> --help
will show available options for that generator. In particular, if generating a new package, you may want to pass
the --directory flag to put the package in a specific subdirectory of the packages directory if you don't
want it placed in the root.
In general, when updating dependencies the fastest method to do so, covering all packages
and taking into account satisfying all peer dependencies, is npx npm-check-updates --deep --peer --dep dev,optional,peer,prod,bundle.
Take special care when upgrading nx - there may be changes to the repository that should be made
when updating, plus there may be changes that should be made to @eternagame/nx-plugin, including changing
our default Nx configuration, changing our generators and adding migrations, etc. Using nx migrate nx
will allow Nx to apply its own migrations, however it will not take into account, for example,
migrating our Nx preset. Additionally there may be changes we want to make based off of migrations
in @nrwl/workspace, even though we don't use it. You should look in the following locations for
changes that we may want to incorporate:
- https://github.com/nrwl/nx/tree/master/packages/nx/presets
- https://github.com/nrwl/nx/tree/master/packages/nx/src/migrations
- https://github.com/nrwl/nx/tree/master/packages/workspace/src/migrations
- And, of course, check the release notes for any new features we may want to take advantage of
If you're on a unix-like system and want to remove all nested node_modules folders,
you can run find . -type d -name node_modules -prune | xargs rm -r
If you want to test changes to packages outside of this repository, you will need a way to install your local version in whatever other repository you're using. There are generally two ways to do this:
If you run npm link -w @eternagame/<package>, this will create a symlink to the local directory
in your global node modules. You can then run npm link @eternagame/<package> in an existing repository
to use the symlinked version instead of retrieving it from npm.
A limitation of npm link is that calls to npm install will still pull from npm rather than using
the global symlink. This is particularly problematic when testing changes to @eternagame/bootstrap
or the @eternagame/nx-plugin:preset generator, as both packages install @eternagame/nx-plugin during the
generation process, and so it will use whatever the latest version is in npm rather than your local copy.
To work around this, you can run a local npm registry using verdaccio.
- In a dedicated terminal, run
npx verdaccioto start the local registry - Run
npm adduser --registry http://localhost:4873to set up an account - Run
npm publish -w @eternagame/<package> --registry http://localhost:4873to publish a package to your local repository - Test out commands by setting the environment variable
NPM_CONFIG_REGISTRY=http://localhost:4873, for exampleNPM_CONFIG_REGISTRY=http://localhost:4873 npx @eternagame/bootstrap. Alternatively, runnpm set registry http://localhost:4873/to set the local registry as your default registry.