Frontend Development Guidelines

Prerequisites

Frontend for Remark42 is built with Preact and Redux.

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 24 or higher (we recommend using NVM for node version autoswitch)
install PNPM 10
run pnpm i inside ./frontend/apps/remark42

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.

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:demo. 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_API_BASE_URL environment variable.

pnpm exec cross-env REMARK_API_BASE_URL=http://127.0.0.1:8080 pnpm dev:custom

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/apps/remark42
pnpm dev

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.

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/apps/remark42, and result files will be saved in ./frontend/apps/remark42/public.

/web is served from two sources. This build output comes first; anything it does not emit is
served from backend/app/webassets/assets, embedded in the backend binary, which is where
privacy.html, markdown-help.html and 400x400.jpeg live. A plain page or image the bundler
does not process belongs there rather than here. Those files sit outside the frontend toolchain,
so prettier, stylelint and pnpm lint do not see them.

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. Eslint reads eslint.config.mjs from the directory it is run in, so point your editor at the app directory: for VSCode, "eslint.workingDirectories": ["frontend/apps/remark42"]

CSS Styles

Component styles use CSS Modules in component.module.css files.
Use root for the component block and camelCase for element and modifier classes; combine classes with clsx.
Keep the stylesheet next to its component, for example app/components/list-comments/list-comments.module.css and app/components/list-comments/list-comments.tsx.

Imports

Imports for TypeScript, JavaScript files should be without extension: ./index, not ./index.ts
Both of the two rules above are reversed inside the dependency-free test layer described under
Testing, and in any module it imports: node's ESM resolver refuses an extensionless specifier and
knows nothing of the alias, so those files write ./types.ts in full and never common/….
Webpack, Jest and tsc all resolve the explicit relative form too, which is why the exception
costs nothing outside those files. It applies to value imports only; a type-only import erases
before either runtime sees it, and keeps the ordinary style
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 the app folder like common/types which maps to ./app/common/types.ts in webpack, tsconfig, and Jest

Testing

Tests come in two layers, and which one a test belongs in is decided by what it needs to run.

Component and integration tests, under Jest

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, and skips *.unit.test.ts
Tests are running on push attempt
Example tests can be found in ./app/components/auth/auth.spec.tsx

Dependency-free tests, `*.unit.test.ts`

Anything that is a function over plain values -- a parser, a reducer, a decoder -- is tested without
a framework, a bundler or node_modules. These files import nothing but the module under test, its
fixtures and node:test, and the runtime strips the types itself:

pnpm test:unit

It needs nothing you do not already have.

The unit job in ci-frontend.yml runs them with no pnpm install step at all. That missing
step is the point: a test that starts needing node_modules to pass has quietly acquired a
dependency, and the job fails instead of hiding it. release.yml runs the same script after an install,
as a second gate and not as the dependency check.

node --test exits 0 on a glob that matches nothing, so on its own it cannot tell a renamed
suffix from a passing run. The CI step counts the files first and fails when none match.

Two rules follow from having no bundler, and both apply to value imports only. A type-only
import is erased before node sees the file, so it may keep the alias and drop the extension, which is why import type { Comment } from 'common/types' is correct inside this layer:

import with the extension in full, ./types.ts, since node resolves nothing else
import by relative path, never by the common/… alias, which only webpack, Jest and tsc know
about

Prefer this layer whenever the thing under test does not genuinely need a DOM. Where a module mixes
the two -- a hook that both reads sessionStorage and computes something -- split the computation
out and test that half here; app/common/intl-message.ts and app/hooks/session-storage.ts are the
pure halves of intl.tsx and useSessionState.ts, kept apart for exactly this reason.

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