Monorepo for Many Sites

The notes are going to become several sites, one for each part: languages, web development, programming and so on. Learning Website: Framework & Architecture 2 decided which folders belong to which site, and Learning Website with Django 1 built that as one Django project. This course builds the same thing with Next.js, so the two can be compared fairly. This first chapter sets up the shape: one repository, one small app for each site, and one shared package that holds the site map.

What a Monorepo Is, and the Alternatives

The Layout

learning-website-nextjs/
├── package.json            workspaces: apps/*, packages/*
├── tsconfig.base.json      one set of TypeScript rules for every app
├── apps/
│   ├── portfolio/          the front page of osztromok.com (port 3000)
│   ├── languages/          languages.osztromok.com        (port 3001)
│   └── webdevelopment/     webdevelopment.osztromok.com   (port 3002)
└── packages/
    └── sites/              the site map and address helpers, shared by every app
        └── src/
            ├── index.ts
            └── index.test.ts

npm workspaces make this work with no extra tool. The root package.json lists the folders that are packages, and npm install links them to each other instead of downloading them: in node_modules/@lw/ there are four links to the real folders, so an app that imports @lw/sites gets the live source file, not a copy. The install took 27 seconds and added 31 packages, with 0 vulnerabilities reported.

The Shared Package: the Site Map

The one thing every site must agree on is which folders belong to which site. It lives in packages/sites as TypeScript source with no build step: its exports field points straight at src/index.ts. It is the Python site map from the Django project, written again in TypeScript:

Because SiteName is made from the object itself, a typo such as "lanugages" is a compile error everywhere it is used. The function siteForPath fails loudly with a NoSiteError for a path that no site owns, instead of guessing. Seven tests check that no folder belongs to two sites, that there are 48 folders, the sidebar and special-prefix rules, the addresses, and that every site has its own development port. They use Node's own test runner, which runs TypeScript files directly, so no test library was added. All 7 pass. (The first run of npm test failed only because the command named a folder instead of a file pattern.)

Is It the Same Map as the Python One?

A one-off script runs the Django project's Python site map, prints it as JSON and compares it key by key with the TypeScript one. Result: identical, 8 sites and 48 folders. That also exposes a weakness: there are now two copies of the map, and a person has to remember to compare them. The script is not part of npm test because it needs the Django project. In the final site only one framework would be used, which removes the problem.

One App per Site

Each app has its own package.json, its own port and its own build. The only unusual line is in its next.config.ts:

Next compiles the app's own files but treats packages in node_modules as already compiled, so without that line the build stops at the package's first export. Links from one site to another come from siteUrl(), so one place decides whether a link is http://systems.localhost:3004/ (development) or https://systems.osztromok.com/ (set LW_ENV=prod when building for the real domain).

The pages are static: they were produced at build time and need no server code to answer. The names *.localhost were not opened in a browser; the requests went to localhost, and the host name does not matter because each app serves only its own site.

The Price of Sharing

A shared package is shared source, not a running service. To see what that means, I changed the title “Languages” to “Languages (changed)” in the package and rebuilt only the languages app:

A change to the package reaches an app only when that app is rebuilt and redeployed, so after changing the package, every app that uses it must be rebuilt, or the sites disagree. For three apps that is one command (18.6 s). For eight it would be roughly 50 s, extrapolated and not measured. A tool such as Turborepo can skip the apps a change cannot affect; it was not used or run here, so that is what it is for, not a tested recommendation.

Hands-On Exercises