Dmitry VerkhoturovandGitHub
4c9ef37cf1
* Move the site from eleventy to hugo The site is built by a single static binary. No node, no package manager, no lockfile, and the toolchain it needed is gone: eleventy, tailwind, postcss, markdown-it and its three plugins, date-fns, prism, npm-run-all, cross-env and html-minifier-terser. Hugo covers most of that itself. Chroma replaces prism, goldmark replaces markdown-it, `--minify` replaces html-minifier-terser, and fingerprinted asset URLs replace the cache-busting `version` shortcode that stamped `Date.now()` into every stylesheet link. `assets/styles.css` is hand-written, since tailwind was the only reason left to keep a package manager. The palette and the light and dark values are custom properties at the top of the file; the minified stylesheet is 15 kB against tailwind's 46 kB, and the whole build 1.0 MB against 1.2 MB. It was matched to the old one by comparing computed styles rather than by eye, which is how the heading weights and line heights, the list marker colour, and the home page heading and sign-off were caught: the last of those had been carried by tailwind utilities written into the markup. The `::: note` container becomes a `note` shortcode taking the emoji to show. Its closer needs a blank line after it, because a shortcode is not a block rule the way `markdown-it-container` was, and without one goldmark keeps the callout inside the open paragraph. The `overflow-x` wrapper around tables and the heading anchors are goldmark render hooks. Syntax guessing is off. Chroma detected a systemd unit file as gdscript and a chat transcript as mysql, and colouring a snippet as the wrong language is worse than not colouring it. The two chroma themes are scoped to opposite sides of the theme switch rather than layered, because they do not declare the same properties on the same tokens: github gives Error a background github-dark never overrides, and styles Punctuation where github-dark leaves it alone. Layered, either leaves a light value applying on a dark page. `[frontmatter] lastmod` resolves through git, then front matter, then file modification time. Without that chain `.Lastmod` falls back to `.Date`, which is zero when a page carries no date, and every page reads `Jan 01, 0001`. `enableGitInfo` is off because the image build context is `site/` alone, where hugo fails hard rather than degrading; `HUGO_ENABLEGITINFO=true` gives real per-page commit dates locally. Three fixes fall out of the move rather than being sought: - `/docs/` redirected nowhere. The stub was a markdown file whose permalink was a template expression while `markdownTemplateEngine` was false, so it never rendered and the URL 404'd. It is an alias now - `/docs/contributing/` pointed at `/docs/contributing/development/`, which has never existed. It points at the backend page - the 404 page was built to `/404/` and nothing served it. Hugo writes it to `/404.html` and reproxy is told to use it The mobile documentation menu is a checkbox and label. `visibility: hidden` on the checkbox, which is what the old `invisible` utility set, takes it out of the tab order, and a label is not focusable on its own, so the menu could not be opened from the keyboard at all. The checkbox is clipped rather than hidden, and its label shows a focus ring. Content is unchanged. Every code block on every page is byte-identical to the eleventy output; the only prose difference is that two example values, `mysite.com` and a quoted `https://demo.remark42.com`, are no longer turned into links, goldmark's linkify being narrower than markdown-it's. `backend/README.md` and `frontend/apps/remark42/README.md` are symlinks into the docs tree and follow it to `site/content/`, as does the path `release.yml` watches. `frontend/CLAUDE.md` described the site as a node and yarn project in four places. * Keep the heading anchors markdown-it generated Goldmark strips punctuation markdown-it kept, so 22 headings holding a dot, slash, apostrophe, question mark, bracket or em dash would take a new id and any link into one from outside the repository would stop resolving. Those headings carry their previous id as well, as an empty target emitted ahead of the heading by the render hook, from a map of content path to old anchor in `data/anchor_aliases.json`. The map was built by matching heading text between the two builds rather than by position, so it survives a heading being added or moved. The hook rather than markdown, because goldmark's `{#id}` attribute syntax cannot express these: it accepts dots, apostrophes and em dashes but treats a slash, a question mark, a bracket or a percent sign as heading text, which is 11 of the 22. The ids are stored percent-decoded, since a browser decodes a fragment before matching, so `#children%E2%80%99s-privacy` finds `children’s-privacy`. Verified by navigating to the awkward ones against the built image and measuring where the page settles: each lands 112px down, which is the header offset the target carries. Three pages carried no title, so the docs template rendered an empty `<h1>` above the heading their markdown already had. They take their titles from that heading text, so neither the wording nor its anchor changes, and the template's `<h1>` carries an id. One in-page link pointed at an anchor goldmark no longer generates. The heading render hook emits no permalink anchor. The one it replaced was an empty `<a href>` with `pointer-events: none`, so it could not be clicked, and its only job was a `::before` spacer that `scroll-margin-top` on the heading already does. Being an `<a href>` it stayed in the tab order, so every heading was an unexplained keyboard stop: eight on the installation page alone. Fragment navigation still lands 112px down, clear of the fixed header. * Harden the site image build and its CI The architecture guard could not fire. `${TARGETARCH:-amd64}` defaulted before the `unsupported arch` branch was reachable, so a build without buildkit put an amd64 hugo inside an aarch64 image and ran only because Docker Desktop emulates it. Reproduced with `--build-arg TARGETARCH=`: `/etc/apk/arch` reported aarch64 and `hugo version` linux/amd64. An empty value is an error now. `Dockerfile.dev` had the same defect and no smoke step to catch it, so it would have failed at `compose up`. The hugo tarball is verified against the release's own `checksums.txt`, and the match is asserted present before it is used: piping grep straight into `sha256sum -c` left the guarantee resting on what the checker does with empty input. Busybox exits 1 there, so it did fail closed, but nothing in the line said so. Verified against a checksums file that does not list the tarball: the build stops before the install. Hugo exits 0 on an empty content tree and emits a two-page shell, which would have been copied, pushed and deployed. The build asserts the home page and a docs page exist. `site/**` pull requests were never built. The only building job is gated on `github.ref == 'refs/heads/master'`, so on a pull request every job skipped and rendered in the checks list the same way a pass does, and the image was first built on the run that also deploys it. A `validate` job builds it with `push: false`, needing no secrets so it works on a fork. `.github/dependabot.yml` watched `/site` for npm packages that are gone. That entry is a docker one, which tracks the alpine base. It does not track the hugo pin and cannot: the docker ecosystem reads `FROM` references, and `ARG HUGO_VERSION` is a bare string in a download URL, so that one is a manual bump and `site/README.md` says so. `Dockerfile.dev` carries a `COPY`, so the dev image works without the compose bind mount, and compose runs as the invoking user rather than root, which on linux left root-owned `public/` and `resources/` in the checkout. Recorded in the backlog: `master` has `required_status_checks` off with an empty check list, so the new job surfaces a red X and does not block a merge. That is a settings decision rather than a code fix.
7.7 KiB
title
| title |
|---|
| Frontend Development Guidelines |
Prerequisites
Frontend for Remark42 is built with Preact and Redux.
{{< note "💡" >}}
We highly recommend checking out Preact documentation.
React libraries are not usable here: the store bindings and the i18n helpers are small local
modules under app/.
{{< /note >}}
In order to inject Remark42 widgets into websites we use iframe and postMessage for communication between a site and the widget.
Simple widgets like counter widget can be injected as a script because it doesn't have its own interface.
While developing, we set up environment which imitates real world example. We serve the page which uses Remark42 config and inject all the widgets on it. You can check it on our demo site. After successful installation you should have the same page running locally.
Installation
You must have at least 2GB RAM or swap enabled for building.
- install Node.js 20 or higher (we recommend using NVM for node version autoswitch)
- install PNPM 10
- run
pnpm iinside./frontend
Running pnpm i will set up pre-commit hooks into your git repository. They are used to reformat your frontend code using prettier and lint with eslint and stylelint before every commit.
{{< note "🚨" >}}
Please use 127.0.0.1 and not localhost to access the server; otherwise, CORS will prevent your browser from authentication to work correctly. You could alter the address for dev auth with the REMARK_URL environment variable.
{{< /note >}}
Development
Run frontend with remote backend
You can run frontend against demo instance of Remark42. This method of running Remark42 frontend code is preferred when you make a translation or visual adjustments that are easy to see without extensive testing. For this method we use our demo instance of Remark42 served on https://demo.remark42.com
For local development mode with Hot Reloading, use pnpm dev:app. In this case, webpack will serve files using webpack-dev-server on 127.0.0.1:9000. By visiting http://127.0.0.1:9000/web/, you will get a page with the main comments' widget communicating with a demo server backend running on https://demo.remark42.com. But you will not be able to log in with any OAuth providers due to security reasons.
You can attach the frontend to the locally running backend from frontend/apps/remark42 folder and providing the REMARK_URL environment variable.
npx cross-env REMARK_URL=http://127.0.0.1:8080 pnpm dev:custom
{{< note "ℹ️" >}}
If you want to redefine env variables such as PORT on your local instance, you can add the .env file to the ./frontend folder and rewrite variables as you wish. For such functional, we use dotenv.
{{< /note >}}
Run frontend with backend locally
This option of running Remark42 frontend code is preferred when you need extensive testing of your code changes, as you'll have your backend and configure it as you want, for example, enable any auth and notifications method you need to test. You can use that set up to develop and test both frontend and backend.
To bring the backend up, run:
cp compose-dev-frontend.yml compose-private.yml
# now, edit / debug `compose-private.yml` to your heart's content
# build and run
docker compose -f compose-private.yml up --build
Then in the new terminal tab or window, run the following to start the frontend with Hot Reloading:
cd frontend
pnpm dev:app
Developer build running by webpack-dev-server supports devtools for React and Redux.
It starts Remark42 backend on 127.0.0.1:8080 and adds local OAuth2 provider "Dev". To access the frontend running by Node, go to http://127.0.0.1:9000/web/. By default, you would be logged in as dev_user, defined as admin. You can tweak any of the supported parameters in corresponded yml file.
Manual testing after changes
Frontend Docker Compose config (compose-dev-frontend.yml) by default skips running backend related tests.
{{< note "🚨" >}}
Before submitting your changes as a Pull Request, run the backend using the docker compose -f compose-dev-frontend.yml build --build-arg SKIP_FRONTEND_BUILD=""; docker compose -f compose-private.yml up command and test your changes against http://127.0.0.1:8080/web/, frontend, built statically (unlike frontend on port 9000, which runs dynamically). That is how Remark42 authors will test your changes once you submit them.
{{< /note >}}
Static build
Remark42 frontend can be built statically, and that's how the production version works: frontend is built and then resulting files embedded into the backend, which serves them as-is. Node is not running when a user starts Remark42, only the backend written in Go programming language, which also serves pre-built frontend HTML and JS and CSS files.
Run pnpm build inside ./frontend, and result files will be saved in ./frontend/apps/remark42/public.
Code Style
- The project uses TypeScript to analyze code statically
- The project uses Eslint and Stylelint to check the frontend code. You can manually run via
pnpm lint - Git Hooks (via husky) installed automatically on
pnpm i. They check and try to fix code style if possible, otherwise commit will be rejected - If you want IDE integration, you need Eslint and Stylelint plugins to be installed. Also, you have configured Eslint for work in subdirectory. For example, you have to add configuration for VSCode like that
"eslint.workingDirectories": ["frontend/apps/remark42"]
CSS Styles
- Now we are migrating to CSS Modules, which is a recommended way of stylization. A file with styles should be named like
component.module.css - Old component styles use BEM notation (at least it should):
block__element_modifier. Also, there aremixclasses:block_modifier - The new way to name CSS selectors is camel-case like
blockElemenModifierand useclsxto combine it - Component base style resides in the component's root directory with a name of component converted to kebab-case. For example,
ListCommentsstyle is located in./app/components/list-comments/list-component.tsx - Any other files should also be named in kebab-case. For example,
./app/utils/get-param.ts
Imports
- Imports for TypeScript, JavaScript files should be without extension:
./index, not./index.ts - If the file resides in the same directory or subdirectory, the import should be relative:
./types/something - Otherwise, it should be imported by absolute path relative to
srcfolder likecommon/storewhich mapped to./app/common/store.tsin webpack, tsconfig, and Jest
Testing
- Project uses Jest as test framework
- Testing Library is used for UI tests
- Jest checks files that match regex
\.(test|spec)\.ts(x?)$, i.e.,comment.test.tsx,comment.spec.ts - Tests are running on push attempt
- Example tests can be found in
./app/components/auth/auth.spec.tsx,./app/store/user/reducers.test.ts
Notes
Frontend part being bundled on docker env gets placed on /src/web and is available via http://{host}/web. For example, embed.mjs entry point will be available at http://{host}/web/embed.mjs