To Demonstrate or Demolish

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.

What's inside?

This monorepo uses pnpm as a package manager. It includes the following Apps and Shared Components / Configs:

Apps and Shared Components / Configs

Everything is 100% TypeScript.

Apps

astro-home: an Astro app; furthest along
nextjs-home: a Next.js app; using the beta app dir
vite-home: a Vite app; highly experimental

Docs

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 Components

shared-icons: a React Component Icon set built from svg-src files
shared-ui: a React UI Component library shared by apps

Shared Configs

eslint-config-shared: shared eslint configurations (includes eslint-config-prettier and eslint-config-next)
tsconfig-shared: shared tsconfig.json used throughout the monorepo

Utilities

This monorepo has some additional tools already setup for you:

TypeScript for static type checking
ESLint for code linting
Prettier for code formatting

Prerequisites to Get Started

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-completion

For more information on what those are doing read the installation docs or the shell completion docs.

Get Started

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 command

For 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.

Package Relationships

To understand the dependencies among packages view "the graph":

pnpm graph

That 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).

Code Checks and Formatting

You can format the code on the command line:

pnpm format

There are also checks for formating, lint, and typescript:

pnpm format-check
pnpm lint-check
pnpm type-check

These 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-check

NOTE: 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.

Package Specific Commands

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.

Develop

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 apps

Build

There 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.

Build Caching

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.

solenoid/demo