Sometimes demonstrating how something works helps understand it.
Along with the ability to demolish what has already been made.
This was started from an official npm starter turborepo, after starting out with turbo it switched to a nx monorepo. Then it removed nx to use pnpm primarily.
This monorepo uses pnpm as a package manager. It includes the following Apps and Shared Components / Configs:
Everything is 100% TypeScript.
astro-home: an Astro app; furthest alongnextjs-home: a Next.js app; using the beta app dirvite-home: a Vite app; highly experimental
docsify-docs: a docsify app; standalone and in docsify aggregator experiments.nextjs-docs: a Next.js app; pages, doc centric. Has docsify aggregator experiments.vitepress-docs: a VitePress app; doc centric. Fits in well with Vite ethos. Can't integrate fully into docsify aggregator experiments.
shared-icons: a React Component Icon set built from svg-src filesshared-ui: a React UI Component library shared by apps
eslint-config-shared: sharedeslintconfigurations (includeseslint-config-prettierandeslint-config-next)tsconfig-shared: sharedtsconfig.jsonused throughout the monorepo
This monorepo has some additional tools already setup for you:
- TypeScript for static type checking
- ESLint for code linting
- Prettier for code formatting
Get pnpm if you don't have it already. You can do this using a standalone
script.
curl -fsSL https://get.pnpm.io/install.sh | sh -
# optionally add command line tab-completion for your shell
pnpm install-completionFor more information on what those are doing read the installation docs or the shell completion docs.
To get started, run the following command:
pnpm install
# or use the "i" alias to do the same thing with less typing
pnpm i
# if you are new to pnpm or want a refresher
pnpm -h # to see all the commands and their aliases
pnpm i -h # to see help for that specific commandFor more information on
pnpm CLI commands use their docs as a starting
point. If you're wondering why pnpm instead of npm see the
Motivation and read other sections of the docs
that look interesting.
To understand the dependencies among packages view "the graph":
pnpm graphThat will always give an up to date version, here's what it looks now without the UI you will get when running locally that is better than this picture.
Having a live version always available helps known how things are organized as things get built up (demo) and torn down (demo).
You can format the code on the command line:
pnpm formatThere are also checks for formating, lint, and typescript:
pnpm format-check
pnpm lint-check
pnpm type-checkThese will run for the whole monorepo across all applications and libraries.
There is also a clean and clean-check using the same naming conventions.
pnpm clean
pnpm clean-checkNOTE: below applies less after the shift from nx centric to pnpm centric
approach happened. It is being left in for now for historical reasons, but
likely to get removed in the future as this repo moves away from nx and build
cache concerns in general.
The above were things you can do repository wide for the entire monorepo. To do
things in a more application or library centric way you will use pnpm to focus
on the parts of the repository you are working directly with.
To develop an app run any of the following:
pnpm pre-dev # One time setup to do code-gen so apps can run
pnpm dev-astro # To work with a single app
pnpm dev-apps-home # To work with multiple home apps
pnpm dev-apps-docs # To work with multiple docs apps
pnpm dev-apps # To work with all appsThere is still more work to figure out of the following commands which match community norms and the needs on this monorepo applications. Some of the tension is caused by figuring out SSR (Server-Side Rendering), CSR (Client-Side Rendering), and Rehydration for rendering on the web. Based on where that tension heads some of the following will become more relevant.
- build
- serve
- start
- preview
If that rendering on the web TLA (three-letter acronym) soup has left you dehydrated please take a 🚰 break before venturing into build caching 🌴 oasis or 🏝️ desert island depending on where things are present or absent.
There is a general need for effective build caching. This can be accomplished with mature tools like Bazel or in a more Turbo specific way currently with Remote Caching at the build artifact level, or the still in alpha Turbo Pack which is intended to cache smaller build artifacts. Both Turbo (repo and pack) approaches seem like they are very well integrated with Vercel the company and the other products thay have like Next.js. It isn't clear if the open source tools will stand alone from the other projects that Vercel is driving forward. The leading approach being tried out is leveraging Nx Caching since that seemed more mature compared to the Turbo approaches.