From 37d72fef8b4e719c768956d0c0fe493fa1abfcde Mon Sep 17 00:00:00 2001 From: waldronmatt Date: Wed, 3 Apr 2024 00:45:00 -0400 Subject: [PATCH] feat(repo): add mascot doc and tweak doc files --- README.md | 18 +++++++----------- docs/repo/ARCHITECTURE.md | 15 ++++++++++++++- docs/repo/COMMANDS.md | 2 +- docs/repo/MASCOT.md | 9 +++++++++ docs/repo/README.md | 4 ++++ docs/repo/SETUP.md | 16 ++++++++++++---- docs/repo/TOOLS.md | 2 ++ 7 files changed, 49 insertions(+), 17 deletions(-) create mode 100644 docs/repo/MASCOT.md diff --git a/README.md b/README.md index 7a4ad976..bde8d6ce 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,13 @@ -blue dragon - # groundwork Welcome to my personal monorepo, a curated collection of boilerplate projects and reusable configurations. This repository serves as my go-to resource for quickly setting up new projects and experimenting with emerging technologies. Whether you're a fellow developer or just curious, feel free to explore and utilize these setups. +## Prerequisites + +For cloning, follow the directions to install [pnpm](docs/repo/SETUP.md#pnpm), [additional packages](docs/repo/SETUP.md#additional-packages), and [nx](docs/repo/SETUP.md#nx). + +For forking, follow all the directions found in the [setup](docs/repo/SETUP.md) page. + ## Installation Install dependencies: @@ -12,12 +16,6 @@ Install dependencies: pnpm i ``` -Install additional required dependencies - -```bash -npx playwright install -``` - ## Getting Started Run local development servers: @@ -40,8 +38,6 @@ pnpm test Compile files and build bundle: -**Note**: Run `pnpm clean` before `pnpm build` to clear `dist` output - ```bash pnpm build ``` @@ -56,7 +52,7 @@ pnpm preview ## Additional Documentation -Additional project setup, commands and documentation can be [found here](docs/repo/README.md). +Additional documentation for this repo can be [found here](docs/repo/README.md). ## License diff --git a/docs/repo/ARCHITECTURE.md b/docs/repo/ARCHITECTURE.md index db24718f..9b0f3806 100644 --- a/docs/repo/ARCHITECTURE.md +++ b/docs/repo/ARCHITECTURE.md @@ -54,7 +54,20 @@ For versioning, we have `excludeDependents` set to `true` in our `lerna` config. ## Package Testing -Internal packages used in other packages are imported by referencing the `lib` / `src` subpath export and installed via `pnpm`'s `workspace:` protocol. +Internal packages used in other packages are imported by referencing the `lib` / `src` subpath export and installed via `pnpm`'s `workspace:` protocol. An example subpath export setup for a package in this repo will typically look like this: + +`package.json` + +```json + "exports": { + ".": { + "types": "./dist/index.d.ts", + "import": "./dist/index.js" + }, + "./*": "./dist/*", + "./src/*": "./lib/*" + }, +``` For example, I have a react component library package that I reference in the storybook and vite-project apps. If I make updates to the react library, I want those changes to automatically refresh (hmr) in those apps. The `lib` / `src` subpath exports allow us to link to the source files so we can avoid rebuilding the component library to see changes. diff --git a/docs/repo/COMMANDS.md b/docs/repo/COMMANDS.md index 2ae2aec6..1a0a6986 100644 --- a/docs/repo/COMMANDS.md +++ b/docs/repo/COMMANDS.md @@ -14,7 +14,7 @@ pnpm clean Delete workspace root `node_modules` and `pnpm-lock.yaml` files: -**Note**: Follow the directions [here](docs/repo/SETUP.md#global-packages) to install `rimraf` globally so errors aren't thrown. +**Note**: Follow the directions [here](docs/repo/SETUP.md#additional-packages) to install `rimraf` globally so errors aren't thrown. ```bash pnpm delete diff --git a/docs/repo/MASCOT.md b/docs/repo/MASCOT.md new file mode 100644 index 00000000..e8fe6d7c --- /dev/null +++ b/docs/repo/MASCOT.md @@ -0,0 +1,9 @@ +# Logo + +![blue dragon](./assets/pnpm-nx-lerna-dragon-logo.png) + +I had some fun with chatgpt's dall-e and fed it logos of pnpm, nx, and lerna; the core software this monorepo uses to manage multiple apps and packages. After several prompts and tweaks, I settled on this image of a blue dragon. + +The dragon's inner body is constructed of tetris-like blocks that is inspired by pnpm's block-like logo. The blue color palette and wave-like patters on the dragon's scales and tail are inspired by nrwl's wave image embedded in the letter X. The dragon is inspired by lerna/lerna-lite's three-headed dragon. + +This fusion of elements in a single dragon symbolizes the cohesive strength and stability these tools provide in managing large-scale codebases. diff --git a/docs/repo/README.md b/docs/repo/README.md index a00f6dc2..0787c8ec 100644 --- a/docs/repo/README.md +++ b/docs/repo/README.md @@ -19,3 +19,7 @@ [Setup](SETUP.md) [Syncpack Commands](SYNCPACK.md) + +## Other Documentation + +[Groundwork Mascot](MASCOT.md) diff --git a/docs/repo/SETUP.md b/docs/repo/SETUP.md index 6883b7f2..0e35aa1d 100644 --- a/docs/repo/SETUP.md +++ b/docs/repo/SETUP.md @@ -4,7 +4,7 @@ Follow the directions [here](https://pnpm.io/installation) to install pnpm. -## Global Packages +## Additional Packages Globally install the `rimraf` package via: @@ -12,12 +12,20 @@ Globally install the `rimraf` package via: pnpm i -g rimraf ``` +Install `playwright` browser binaries: + +```bash +npx playwright install +``` + ## Git Hooks -Install husky and hooks in your repo for the first time: +Install husky hooks: + +**Note**: `pnpm` should automatically run `prepare` when installing ```bash -pnpm exec husky init +pnpm prepare ``` ## NX @@ -62,7 +70,7 @@ Create a `security` PR label. Renovate will automatically create a PR and apply ## Kodiak -Follow the directions [here](https://kodiakhq.com/docs/quickstart) to set up Kodiak. +Follow the directions [here](https://kodiakhq.com/docs/quickstart) to set up Kodiak. Make sure to [configure GitHub branch protection](https://help.github.com/en/articles/configuring-protected-branches). Setup [required status checks](https://docs.github.com/en/github/administering-a-repository/enabling-required-status-checks) to prevent failing PRs from being merged. Create a `wip` PR label. When you set the `wip` label on a PR, Kodiak will not merge it. diff --git a/docs/repo/TOOLS.md b/docs/repo/TOOLS.md index 1fa3d162..0b4aa11d 100644 --- a/docs/repo/TOOLS.md +++ b/docs/repo/TOOLS.md @@ -34,6 +34,8 @@ [`commitizen`](https://github.com/commitizen/cz-cli): For enabling `cz-conventional-changelog` via the command line +[`only-allow`](https://github.com/pnpm/only-allow): For forcing a specific package manager to be used on a project + ## CICD [`github actions`](https://docs.github.com/en/actions): For CI/CD