13 KiB
Monorepo — Design
Date: 2026-04-24 Status: Approved, ready for plan
Goal
Restructure the hudozka repo into an npm-workspaces monorepo. Consolidate the current Next.js app, the Vite-based hudozka-writer, and the Node-based migrate-to-pocketbase under apps/. Extract reusable UI primitives, hooks, and utilities into packages/ scoped as @hudozka/*. Leave the PocketBase directory (pb/) untouched.
Non-goals
- No behavioral changes to any app. This is a move + reorganization only.
- No adoption of
@hudozka/uior@hudozka/hooksinsidehudozka-writer. Writer is relocated, not rewired. - No Turborepo or other orchestration layer.
- No switch to built-output packages. Packages are consumed as TypeScript source.
- No publishing to npm. All packages are private workspace-only.
Workspace layout
hudozka/
├─ apps/
│ ├─ hudozka/ # Next.js app (was repo root)
│ │ ├─ app/
│ │ ├─ src/
│ │ ├─ public/
│ │ ├─ Dockerfile # moved here from repo root
│ │ ├─ next.config.ts
│ │ ├─ tsconfig.json
│ │ └─ package.json
│ ├─ hudozka-writer/ # was modules/hudozka-writer
│ └─ migrate-to-pocketbase/ # was modules/migrate-to-pocketbase
├─ packages/
│ ├─ ui/ # @hudozka/ui
│ ├─ hooks/ # @hudozka/hooks
│ ├─ utils/ # @hudozka/utils
│ └─ text/ # @hudozka/text
├─ pb/ # PocketBase — untouched
├─ docs/
├─ .github/workflows/
├─ package.json # workspaces only
├─ tsconfig.base.json
├─ eslint.config.js
├─ vitest.config.ts # root web-app config stays; packages opt in
└─ mise.toml
App package names are not scoped (hudozka, hudozka-writer, migrate-to-pocketbase). Shared packages use the @hudozka/* scope.
Package boundaries
All packages/* are consumed as TypeScript source. Each has:
{
"name": "@hudozka/<name>",
"private": true,
"type": "module",
"exports": { ".": "./src/index.ts" }
}
No build step. Next, Vite, and node --experimental-strip-types handle TS source natively.
@hudozka/utils
- Source:
array.ts,string.ts,url.ts,math.ts,image.ts,file.ts,date.ts(+ co-located.test.ts) - Runtime deps:
date-fns - Peer deps: none
- Consumers:
apps/hudozka;apps/migrate-to-pocketbaseif it uses any
@hudozka/text
- Source:
text.ts - Runtime deps:
markdown-it,typograf - Dev deps:
@types/markdown-it - Peer deps: none
- Consumers:
apps/hudozka
@hudozka/hooks
- Source:
useToggle.ts,useLockBodyScroll.ts,useMediaQuery.ts,useMobile.ts,useReducedMotion.ts(+ co-located.test.ts) - Peer deps:
react(>=19) - Consumers:
@hudozka/ui,apps/hudozka
Business-coupled hooks (useDarkTheme, useAccessibility — depend on the Valtio theme store) stay in apps/hudozka/src/hooks/.
@hudozka/ui
- Components:
Box,Button,Panel,Title,Overlay(+Transitionsubcomponent) with co-located.test.tsxand CSS Modules - Runtime deps:
classnames - Peer deps:
react(>=19),react-dom(>=19) - Workspace deps:
@hudozka/hooks - Consumers:
apps/hudozka
Picture (imports next/image, next/link, useDarkTheme) and ThemeColor (bridges Valtio theme store) stay in apps/hudozka/src/components/ to avoid leaking Next and business state into shared packages.
Dependency graph
apps/hudozka ─┬─> @hudozka/ui ──> @hudozka/hooks
├─> @hudozka/hooks
├─> @hudozka/utils
└─> @hudozka/text
apps/hudozka-writer (no workspace deps — relocated only)
apps/migrate-to-pocketbase ──> @hudozka/utils (optional; only if used)
Acyclic. ui → hooks is the only inter-package edge.
TypeScript
Root tsconfig.base.json
Shared compiler options:
{
"compilerOptions": {
"target": "ES2020",
"lib": ["dom", "dom.iterable", "esnext"],
"module": "esnext",
"moduleResolution": "bundler",
"jsx": "react-jsx",
"strict": true,
"skipLibCheck": true,
"esModuleInterop": true,
"forceConsistentCasingInFileNames": true,
"resolveJsonModule": true,
"verbatimModuleSyntax": true,
"moduleDetection": "force",
"noEmit": true,
"allowJs": true,
"incremental": true
}
}
Per-workspace tsconfig
apps/hudozka/tsconfig.json— extends base; adds"plugins": [{ "name": "next" }];"paths": { "@/*": ["src/*"] }; includes.next/types/**.apps/hudozka-writer/tsconfig.json— moved as-is; updated to extend base.apps/migrate-to-pocketbase/tsconfig.json— new, minimal; extends base; Node-flavoredlib.packages/*/tsconfig.json— extends base;include: ["src/**/*"]; no path aliases.
Resolution
npm workspaces symlinks @hudozka/* into node_modules. "exports" points to source. No project references needed.
Path aliases
@/* → src/* stays only in apps/hudozka. Packages use short relative imports. This matches the existing rule in the project's CLAUDE.md.
ESLint
Single flat eslint.config.js at repo root. Changes vs. current:
- Drop
modules/exclusion; addapps/*/dist,apps/*/.next,public/static/to global ignores. eslint-config-nextscoped toapps/hudozka/**via a targeted config block.- Style rules unchanged: no semicolons, double quotes, 4-space indent, always-multiline trailing commas,
eol-last.
Vitest
apps/hudozka/vitest.config.tsandapps/hudozka/vitest.setup.tsx— moved as-is.packages/ui/vitest.config.tsandpackages/hooks/vitest.config.ts— new, minimal; include jsdom/happy-dom setup for component tests.packages/utils/vitest.config.ts— new, no DOM setup needed.packages/text/— no tests currently;testscript is a no-op runnable.
Scripts
Root package.json
{
"private": true,
"workspaces": ["apps/*", "packages/*"],
"scripts": {
"dev": "npm run dev -w apps/hudozka",
"build": "npm run build -w apps/hudozka",
"start": "npm run start -w apps/hudozka",
"lint": "eslint .",
"format": "eslint --fix .",
"test": "npm test --workspaces --if-present"
}
}
- Root
dev/build/startdefault to the web app (most common path). - Other apps run via
-w:npm run dev -w apps/hudozka-writer,npm run migrate -w apps/migrate-to-pocketbase. --if-presentmakes packages without atestscript silent, not failing.
Per-app/package scripts
apps/hudozka— existingdev/build/start/lint/format/testrelocated.apps/hudozka-writer— existingdev/build/preview.apps/migrate-to-pocketbase— existingmigrate/wipe.packages/*—test: vitest runwhere applicable.
Dev-dep hoisting
Shared tooling (typescript, eslint, vitest, @testing-library/*, happy-dom) lives only in the root devDependencies. Workspaces resolve them from the hoisted root node_modules. Apps declare their runtime deps in their own dependencies.
CI / CD
.github/workflows/test-app.yml
npm ciat root, thennpm run lint+npm test+npm run build.- No per-workspace fan-out.
.github/workflows/build-app.yaml
context:stays.(repo root).file:becomes./apps/hudozka/Dockerfile.
Dockerfile (at apps/hudozka/Dockerfile)
Multi-stage, workspace-aware:
- Install stage — copy root
package.json,package-lock.json, everyapps/*/package.json+packages/*/package.json. Runnpm ci. - Build stage — copy the rest of the monorepo. Run
npm run build -w apps/hudozka. - Runner — copy
apps/hudozka/.next/standalone,apps/hudozka/.next/static,apps/hudozka/publicinto the final image. Standalone output already bundles what it needs frompackages/*.
Runtime path change: ./.next/standalone → ./apps/hudozka/.next/standalone.
Migration sequencing
Each phase ends with a verification gate (npm install + lint + test + build all pass).
Phase 1 — Workspace skeleton
- Add
workspaces: ["apps/*", "packages/*"]to rootpackage.json. - Create empty
apps/,packages/directories. - Create
tsconfig.base.json. - Gate:
npm installsucceeds.
Phase 2 — Relocate writer and migrate apps
git mv modules/hudozka-writer apps/hudozka-writergit mv modules/migrate-to-pocketbase apps/migrate-to-pocketbase- Update each app's tsconfig to extend
../../tsconfig.base.json(writer already has a tsconfig; migrate gets a new minimal one). - Remove empty
modules/directory. - Gate:
npm run dev -w apps/hudozka-writerandnpm run migrate -w apps/migrate-to-pocketbasework.
Phase 3 — Relocate Next app to apps/hudozka
git mvall top-level Next artifacts intoapps/hudozka/:app/,src/,public/,next.config.ts,next-env.d.ts,tsconfig.json,tsconfig.tsbuildinfo,vitest.config.ts,vitest.setup.tsx,eslint.config.js(temporary; consolidated in phase 6),Dockerfile.- Split root
package.json: runtime deps + web-specific scripts move toapps/hudozka/package.json; root keeps only workspace config and shared dev deps. - Update
apps/hudozka/tsconfig.jsonto extend the root base. - Update
.github/workflows/build-app.yamlfile:path. - Update Dockerfile: context remains repo root;
COPYpaths now targetapps/hudozka/*; adjust standalone output path. - Gate:
dev,test,buildofapps/hudozkaall pass.
Phase 4 — Extract @hudozka/utils
- Create
packages/utils/withpackage.json,tsconfig.json,src/,src/index.ts. git mvarray.ts,string.ts,url.ts,math.ts,image.ts,file.ts,date.ts(+ tests) fromapps/hudozka/src/lib/topackages/utils/src/.- Move
date-fnsfromapps/hudozka/package.jsontopackages/utils/package.json. - Codemod imports in
apps/hudozka:@/lib/array→@hudozka/utils, etc. - Gate: lint + test + build pass.
Phase 5 — Extract @hudozka/text, @hudozka/hooks, @hudozka/ui
Order: text → hooks → ui (ui depends on hooks).
@hudozka/text: movetext.ts,markdown-it,typograf,@types/markdown-it. Codemod imports.@hudozka/hooks: moveuseToggle,useLockBodyScroll,useMediaQuery,useMobile,useReducedMotion(+ tests).useDarkThemeanduseAccessibilitystay inapps/hudozka. Codemod imports.@hudozka/ui: moveBox,Button,Panel,Title,Overlay(+ tests, CSS Modules).PictureandThemeColorstay inapps/hudozka/src/components/. Moveclassnamesdep. Codemod imports; Overlay's hook imports become@hudozka/hooks.- Gate after each package: lint + test + build pass.
Phase 6 — Consolidate ESLint & Vitest configs
- Move
eslint.config.jsfromapps/hudozka/back to repo root; scope Next config toapps/hudozka/**. - Add minimal
vitest.config.ts(and setup where needed) topackages/uiandpackages/hooks;packages/utilsgets a non-DOM config. - Update root
package.jsonscripts as above. - Gate:
npm run lintat root lints everything;npm testruns all workspace tests.
Phase 7 — Cleanup
- Delete orphaned files (stray
.DS_Store, empty directories). - Update root
README.mdwith new layout (brief). - Update root
CLAUDE.md(Commands, Key Directories, Architecture paths). - Spot-check
.github/workflows/*, Dockerfile paths,mise.toml.
Risks and mitigations
- CSS Modules in
@hudozka/uiconsumed as source. Next and Vite import.module.cssnatively; confirmed by currentsrc/ui/usage. No build step needed. If a future consumer doesn't handle CSS, it must add that support itself. - Standalone Next output path change. The Dockerfile runner copies a different path now. Explicit step in phase 3; guarded by the build gate.
- Hoisted dev deps. Different workspaces could theoretically disagree on major versions (e.g.,
typescript). Mitigation: all TS tooling lives only at the root; no workspace declares a conflicting version. experimental-strip-typesinmigrate-to-pocketbase. Still works when the script imports@hudozka/utilsas source — Node strips types across the import boundary. Verified by the fact that utils has no non-TS-native syntax.eslint-config-nextglobs. Flat-config scoping must precisely targetapps/hudozka/**to avoid leaking Next rules into packages. Phase 6 explicitly tests this by runningnpm run lintat root.
Deferred
- Adopting
@hudozka/uior@hudozka/hooksinapps/hudozka-writer. - Turborepo (revisit if build times or CI duration warrant it).
- Built-output packages +
.d.tsemission (revisit if publishing or non-TS consumers appear). - Further extraction from
apps/hudozka/src/(e.g., splittingremote/, breaking upcomponents/) — out of scope for this migration.