Dmitry VerkhoturovandGitHub
a5b2fe3cfc
Four upgrades that were finished but never merged, the compiler collapse
they enable, and the dependency sweep that follows. Direct
devDependencies go from 78 to 60 and dependencies from 10 to 9.
Three were doing the same job: `ts-loader` stripped types in webpack,
`babel-loader` did everything else, and `@swc/jest` repeated both for the
tests with its own copy of the JSX settings. Babel is the one that
survives, because the `data-testid` stripper has no equivalent elsewhere.
`ts-loader` ran `transpileOnly: true`, so it only stripped types, which
`@babel/preset-typescript` does; `fork-ts-checker-webpack-plugin` was
already what type-checks. Jest runs `babel-jest` against the same
`.babelrc.js` the bundle uses, passed as `configFile` because a
file-relative babel config does not reach the `node_modules` packages in
`transformIgnorePatterns`, and `jest.config.mjs` is plain ESM because a
`.ts` config is compiled against `tsconfig.json`, whose
`verbatimModuleSyntax` rejects ESM syntax in a file the package has not
declared as a module.
That removes `ts-loader`, `@swc/jest` and `@swc/core`. The last was
pinned to 1.2.205 from 2022 with no way forward, because newer builds
emit non-configurable exports and break `jest.spyOn` across 13 suites.
Babel compiles a file at a time with no type information, so it cannot
tell a type-only import from a real one and keeps the module. One line,
`import { boundActions } from './connected-comment'`, pulled the whole
redux store into `last-comments.mjs` and doubled it. `verbatimModuleSyntax`
and `@typescript-eslint/consistent-type-imports` mark them properly; the
statement has to be a separate `import type`, since verbatim semantics
keep an inline `import { type X }` and load the module anyway.
The legacy and modern compilations produced the same bytes. Both read the
same browserslist query, `defaults, not IE 11, not samsung 12` resolves to
chrome 109 and up, and nothing in the source needs transforming for that
set, so 28 of the 29 output pairs were byte-identical.
That made the module/nomodule switch worse than redundant: it served the
`.js` file to browsers with no ES module support, and those files carried
`??`, `?.` and class fields, so the fallback handed its own audience a
syntax error. There is now one bundle, always loaded as a module, in the
five templates and in the seven `site/` documents integrators copy from.
A production build emits 29 files rather than 58, in about 3 seconds
rather than 17. Two of those documents did not work at all beforehand:
the SPA snippet could not parse, and the subdomain example had an
unterminated string.
`@babel/core` 8 declares `^22.18 || >=24.11` and `size-limit` 13 declares
`^22.18 || ^24 || >=26`, so 20 was below the floor of two things installed
here; pnpm only warns, which is why every build passed. All seven places
the frontend pins it move together. `site/` is untouched: it builds with
yarn and eleventy and installs neither.
`eslint --print-config` before and after gives 173 active rules on an
application file against 172, and 172 on a spec file and a plain JS file
against 171. What is gone is three `flowtype` rules with no Flow here,
`no-new-object` and `no-new-symbol` whose upstream replacements are on,
`react/forbid-foreign-prop-types` with no propTypes anywhere, and, on TS
only, `no-useless-constructor`, whose typescript-eslint version is on at
error. `@babel/core` is pinned to 8 across the workspace because
`@jest/transform` and `istanbul-lib-instrument` depend on 7 outright; a
second scoped override holds `eslint-config-preact` on 7, since its
`@babel/eslint-parser` loads babel 7 syntax plugins.
`fast-async` rewrote every async function into nodent promise chains,
calls babel's `transform` synchronously, which babel 8 removed, and every
browser in the target list runs async natively. `prefresh` blew its stack
on `createContext` under babel 8 with no newer release to move to, which
compiled `intl.tsx` and `store/context.tsx` into throwing stubs, so
`pnpm dev:app` could not run the widget at all. `core-js` is not injected
now that `useBuiltIns` is gone, `postcss-custom-properties` was reached
directly although nothing declared it and resolved only through pnpm's
private hoist directory, and `cssnano` ran in both postcss chains although
`CssMinimizerPlugin` already uses it.
`pnpm lint`, `pnpm test` and `pnpm build` now work from `frontend/` as
`CLAUDE.md` and the contributing guide have always said they do; the
workspace root defined none of them.
6.4 KiB
6.4 KiB
Remark42 Development Guidelines
Build/Test/Lint Commands
- Backend:
- Run server:
make rundev - Build:
make backend - Race test:
make race_test
- Run server:
- Backend Testing:
- Run all tests:
cd backend/app && go test -timeout=60s -count 1 ./... - Run single test:
cd backend/app && go test -run TestName ./path/to/package - IMPORTANT: Run example tests:
cd backend/_example/memory_store && go test -race ./... && go build -race ./...
- Run all tests:
- Frontend:
- Development:
cd frontend && pnpm dev:app - Tests:
cd frontend && pnpm test
- Development:
- End-to-end:
make e2edrives the widget in a real browser; seee2e/README.md. Build-tagged, sogo test ./...never runs it. - Lint:
- Backend:
cd backend && golangci-lint run - IMPORTANT: Example lint:
cd backend/_example/memory_store && golangci-lint run --config ../../.golangci.yml - Frontend:
cd frontend && pnpm lint - Before committing: Always run tests and linter on both main backend AND examples
- Backend:
- Go module changes:
- Any change to
backend/go.modorbackend/go.sumrequiresgo mod tidyinbackend/_example/memory_storein the same commit. That covers dependency bumps, adding or removing a dependency, and changing thegodirective, not only version updates. - Only
go mod tidythere, notgo mod vendor: the example's vendor directory is gitignored (.gitignore:26), so its output is never committed, while a stale local copy silently becomes what the example resolves against. - The example module replaces
github.com/umputun/remark42/backendwith../../, so it carries the backend's dependencies as indirect entries. Leaving them stale fails thetest examplesCI step withgo: updates to go.mod needed; to update it: go mod tidy. - This applies to Dependabot pull requests too: the bot updates
backend/only, so its Go module PRs need the example tidied before they can go green.
- Any change to
Release Procedure
Remark42 uses two tags for each release:
vX.Y.Z- product release tag used by GitHub releases, GoReleaser binary artifacts, and Docker image publishing.backend/vX.Y.Z- nested Go module tag forgithub.com/umputun/remark42/backend.
Release flow:
- Create the GitHub release for
vX.Y.Zwith titleVersion X.Y.Z. The GitHub release must exist before thevX.Y.Ztag reaches the remote;gh release create vX.Y.Zsatisfies this because it creates and pushes the tag. - The
vX.Y.Ztag triggers GoReleaser, which builds and uploads binary artifacts to the existing release. - Create and push the matching backend module tag pointing at the same commit:
git fetch origin --tags
git tag backend/vX.Y.Z vX.Y.Z
git push origin backend/vX.Y.Z
GoReleaser must ignore backend/* tags in .goreleaser.yml so release notes and current-tag detection use only product tags. Docker image publishing stays separate and is handled by the existing Docker workflow.
For local artifact runs, install GoReleaser, Go 1.25, Node 24+, PNPM 10, and Perl, then use make release. The target runs a snapshot/no-publish GoReleaser build, leaves local artifacts and metadata in dist/, and cleans generated frontend embed files after GoReleaser exits. Do not run raw goreleaser release for local artifacts unless you also run ./scripts/cleanup-release-assets.sh afterward.
Milestones and Issue Labels
Milestones — one vX.Y.Z milestone per release. Assign every merged PR, and every issue closed by a code change, to the milestone of the release it shipped in.
- Decide which release a PR belongs to by whether its merge commit is contained in a release tag — not by comparing dates (a tag can be cut from an earlier commit, or moved).
git fetch --tags, thengit tag --contains <merge_sha> | grep '^v' | sort -V | head -1is its release. If no release tag contains it yet, it belongs to the next (unreleased) version's milestone — create it if missing (gh api repos/umputun/remark42/milestones -f title="vX.Y.Z"). - An issue gets a milestone only when it was closed by a code change (a linked closing PR/commit); take the milestone from that PR/commit (via the commit-in-tag rule). Issues closed as
duplicate/invalid/wontfix/answered get no milestone. - Find unassigned:
gh pr list --state merged --search "no:milestone",gh issue list --state closed --search "no:milestone". Assign withgh pr edit N --milestone "vX.Y.Z"/gh issue edit N --milestone "vX.Y.Z".
Issue labels — classify each issue with a type and an area (add priority when relevant):
- Type:
bug,enhancement,question,documentation,discussion - Area:
backend,frontend,site,CI,design,localization - Priority:
important,minor,some day - Contribution:
help wanted,good-first-issue - Resolution (on close, when applicable):
duplicate,invalid,wontfix,no-action-needed - PR auto-labels (applied by Dependabot/Actions, not manual PRs):
dependencies,go,javascript,github_actions
Code Style
- Backend: Formatting with golangci-lint, strict error handling
- Frontend: TypeScript with ESLint, Stylelint and Prettier
- Imports: Group stdlib, external packages, then internal packages
- CSS: All components use CSS Modules (
component.module.css). Class naming: BEM block =.root, elements = camelCase, modifiers = camelCase. Useclsxfor conditional class composition.raw-content.cssis the only global CSS file (syntax highlighting utility). Root wrapper keeps bare.dark/.lighttheme class — 8+ module CSS files depend on:global(.dark)ancestor.comment_highlightinguses:global()for imperativeclassListusage in root.tsx
Key Backend Packages
- Web/API:
github.com/go-pkgz/routegroup,github.com/go-pkgz/rest - Auth:
github.com/go-pkgz/auth/v2 - Logging:
github.com/go-pkgz/lgr - Testing:
github.com/stretchr/testify - Notifications:
github.com/go-pkgz/notify
Repository Structure
- Backend: Go server using BoltDB for storage
- Frontend: Preact/Redux-based UI with iframe embedding
/webis served from two sources, in lookup order: the frontend build output (frontend/apps/remark42/public, embedded atbackend/app/cmd/webor read from--web-root), thenbackend/app/webassets/assets, embedded in the binary. A plain page or image the bundler does not process belongs inwebassets; anything needing templating or the widget's CSS/JS goes through webpack. A name present in both is served from the frontend build.