moker

moker

No more struggles setting up new JavaScript repository. Kick-start single-purpose repos, monorepos, monorepo workspaces and common tooling:

# initialize a monorepo
yarn dlx moker create --monorepo my-repo
cd my-repo

# install common tools
yarn moker use prettier husky lint-staged doctoc semantic-release

# create workspaces
yarn moker add --template express server
yarn moker add --template cra client

Features

• 👢 Kick-start a new repo or monorepo using Yarn
• 🧰 Plugins to use pre-configured common tooling
• ➕ Quickly add workspaces to a monorepo
• 🧬 Workspace templates for a shared library, React app, API or CLI
• ⚡ Extensible, bring your own plugins

🤓 The core plugins make some assumptions you may not agree with. If that's the case, this tool is probably not for you. The defaults used are documented below and marked with a nerd-face emoji so you should be able to get a clear picture of what to expect.

Table of contents

• Getting started
  • Prerequisites
  • Create monorepo
  • Use plugins
  • Add workspace
• Available plugins
  • dependabot monorepo
  • devcontainer monorepo
  • doctoc monorepo
  • github-actions monorepo
  • husky monorepo
  • jest workspace
  • lint-staged monorepo
  • prettier monorepo
  • semantic-release monorepo
  • todos workspace
  • typescript workspace
• Available templates
  • bandersnatch workspace
  • common monorepo
  • cra workspace
  • express workspace
  • lib workspace
• Contributing
  • Roadmap
  • Development
  • Devcontainer
  • Credits

Getting started

Prerequisites

You will need Node v14+ and Yarn v2+ in order to use moker.

• Install Node with nvm or using nodesource.
• Install Yarn using these simple steps:

  corepack enable
  corepack prepare yarn@stable --activate
  

Create monorepo

Create a new monorepo:

yarn dlx moker create --monorepo my-repo

This will initialize a new monorepo in the my-repo directory.

⚠️ Note that we use yarn dlx moker to create a new monorepo. Once we are inside our monorepo, we can simply use yarn moker to execute commands.

🤓 The monorepo is initiated with Yarn without Zero-Installs and in legacy nodeLinker: node-modules mode because a lot of packages are not yet compatible with PnP or require a workaround.

Use plugins

Of course you want additional tools installed at the monorepo level, add them with:

cd my-repo
yarn moker use prettier husky lint-staged

Plugins may work together. For example, lint-staged will install a pre-commit hook which formats code if prettier and husky are installed. The order in which plugins are added does not matter.

See the section available plugins for a list of options.

💡 To quickly get started with the most common plugins, use a monorepo template like so:

yarn dlx moker create --template common my-repo

Add workspace

To add a new workspace (a.k.a. monorepo package) to your monorepo, use:

yarn moker add my-workspace

Workspaces are added in a customizable subdirectory of the monorepo (the default is packages).

You can also use a workspace template, e.g.:

yarn moker add --template lib shared
yarn moker add --template express server
yarn moker add --template cra client
yarn moker add --template bandersnatch cli

See the section available templates for a list of options.

Available plugins

dependabot monorepo

This plugin adds a Dependabot configuration to your monorepo with an updater for NPM packages.

If you have the github-actions plugin installed, it will add an updater for GitHub Actions workflows.

devcontainer monorepo

This plugin creates a Development Containers configuration using the typescript-node image.

If you have the prettier plugin installed, it will add the Prettier VS Code extension.

doctoc monorepo

This plugin adds a script to generate a table of contents for the README using doctoc.

If you have the husky plugin installed, it will also add a pre-commit hook.

github-actions monorepo

This plugin creates a simple ci.yml GitHub Actions workflow.

If you have the prettier plugin installed, this will also setup a lint.yml workflow.

If you have the semantic-release plugin installed, this will also setup a release.yml workflow. This workflow needs these secrets to be added to your repository:

• GH_TOKEN: a GitHub token with read/write access to your repository
• NPM_TOKEN: an NPM token with publish access to your packages

🤓 The workflows will use the main branch by default, but it is trivial to change this.

husky monorepo

This plugin sets up Husky at the monorepo level.

jest workspace

This plugin sets up Jest and adds a test and test:watch script to both the workspace and the monorepo.

lint-staged monorepo

This plugin sets up lint-staged at the monorepo level.

If you have the prettier plugin installed, this will setup a task to format staged files using prettier --write --ignore-unknown.

If you have the husky plugin installed, this will setup a pre-commit hook to run yarn lint-staged.

prettier monorepo

This plugin sets up Prettier.

🤓 Prettier is installed with this configuration:

proseWrap: always

We only set this proseWrap override because we think markdown files should always be truncated to match whatever the printWidth setting is. This makes it so much easier to read and write markdown files!

semantic-release monorepo

⚠️ This is work in progress

Current plan:

• Move to yarn npm publish
• Set "private": true in root package
• This will cause semantic-release/npm to skip publish step
• We add exec plugin and use yarn workspaces foreach npm publish
• We can remove .npmrc file
• We need to modify .yarnrc.yml / .releaserc.json
• We can get rid of "publishConfig" in workspaces pkg
• We need to change prepublishOnly to prepublish
• Document weird command (esp. JSON string echo)
• npm whoami fix not needed!

This may be outdated:

This plugin sets up semantic-release. It uses a workaround so that it can be used in a monorepo, which is to set up a .npmrc file containing:

workspaces = true
workspaces-update = false

This causes both npm version and npm publish to be run for each monorepo in the semantic-release context.

Please note that the root repository is not published. Furthermore, make sure that the root package.json doesn't contain:

"private": true

Otherwise, the semantic-release process will skip the publish step.

🤓 The release configuration will use the main branch by default, but it is trivial to change this.

⚠️ The semantic-release plugin in our monorepo configuration is currently broken due to an issue with their npm plugin (see semantic-release/npm#529) [this issue with their npm a]. Take a look at patch-semantic-commit.js in this repository for a workaround.

todos workspace

This plugin adds a script to generate a TODO markdown file from all code annotations using leasot.

If you have the husky plugin installed, it will also add a pre-commit hook.

typescript workspace

This plugin sets up TypeScript and adds a build and build:watch script to both the workspace and the monorepo.

Available templates

bandersnatch workspace

Scaffolds a simple bandersnatch CLI app tool with the typescript and jest plugins.

common monorepo

This is the only monorepo template at this point. It simply installs all available monorepo plugins.

cra workspace

Uses create-react-app to scaffold a React.js app (web client).

express workspace

Scaffolds a simple express HTTP app with the typescript and jest plugins.

lib workspace

A plain shared library template with the typescript and jest plugins.

Contributing

Contributions are very welcome!

Roadmap

• Adapt for non-monorepo use-cases (WIP)
• Add LICENSE file to monorepo
• Support for swc/esbuild
• A compat lib (which builds cjs and mjs targets)
• Blog post / tutorial
• Docs for writing custom plugins / templates
• github-actions plugin
• devcontainer plugin
• leasot (todos) plugin
• doctoc plugin
• semantic-release plugin
• Port templates
• Support for BYO plugins/templates
• Remove plugins

Also see TODO.md.

Development

To run the moker CLI from source, run:

yarn start

Note that you can create a new monorepo for testing purposes outside the current working directory with:

yarn start create /path/to/my-repo

Devcontainer

A devcontainer configuration is included in this repo to get started quickly.

Credits

©️ Copyright 2022 Joram van den Boezem
♻️ Licensed under the MIT license
🤔 Moker? MOnorepo KickstartER

Changelog

0.5.0 (2022-11-28)

Features

• support single-purpose repos (#84) (a9c6532)