Short guide to h's new Preact-based frontend code

[seanh]

Tech stack

We use TypeScript not JavaScript: https://www.typescriptlang.org/.

And Preact not React: https://preactjs.com/ (but I highly recommend https://react.dev/learn).

We use Tailwind for CSS: https://tailwindcss.com/. If you haven't tried "utility first CSS" before this is very different, but once you get used to it it's amazing! Here's a good post about utility-first CSS, from the creator of Tailwind. This post is also good, and this one.

The frontend-shared repo contains various frontend components that're shared across our codebase. You can see a demo of them at https://patterns.hypothes.is/.

There are separate make commands for frontend things: make frontend-{format,lint,tests,typecheck}. make sure will also run these (along with all the backend stuff), as will CI.

PRs

#8789 was the PR that originally added this new tech stack to h and added a first version of the create-group page using the new stack. The code has been extended and refactored somewhat since then, but the PR is still a good overview of everything that's involved in adding a new page using the new stack.

Pyramid routes

There's a few different routes/URLs used by the new group management pages (one for the group edit page, one for the group members page, etc):

h/h/routes.py

Lines 224 to 241 in 052e9e1

	config.add_route(
	"group_edit",
	"/groups/{pubid}/edit",
	factory="h.traversal.GroupRequiredRoot",
	traverse="/{pubid}",
	)
	config.add_route(
	"group_edit_members",
	"/groups/{pubid}/edit/members",
	factory="h.traversal.GroupRequiredRoot",
	traverse="/{pubid}",
	)
	config.add_route(
	"group_moderation",
	"/groups/{pubid}/moderate",
	factory="h.traversal.GroupRequiredRoot",
	traverse="/{pubid}",
	)

For the login and signup pages of course there are already /login and /signup routes, so you shouldn't need to add any new routes.

Pyramid views

The Pyramid view for the group edit page is h/views/groups.py::GroupCreateEditController.edit():

h/h/views/groups.py

Lines 34 to 52 in 052e9e1

	@view_config(
	route_name="group_edit", request_method="GET", permission=Permission.Group.EDIT
	)
	@view_config(
	route_name="group_edit_members",
	request_method="GET",
	permission=Permission.Group.EDIT,
	)
	@view_config(
	route_name="group_moderation",
	request_method="GET",
	permission=Permission.Group.EDIT,
	)
	def edit(self):
	"""Render the page for editing an existing group."""
	return {
	"page_title": "Edit group",
	"js_config": self._js_config(),
	}

Note that the same view handles three different routes group_edit, group_edit_members and group_moderation, and all three routes use the same template (defined in the @view_defaults class decorator).

This is because a single Preact app handles all three pages (more on that below), so Pyramid just needs to bootstrap the same Preact app for all three URLs. You'll want to do something similar for the different "pages" of the new login and signup mockups.

The view pretty much just renders the template. The one important thing to note is the js_config dict that is passed to the template. This contains the config settings for the Preact app.

Jinja2 template

The group edit, group members and group moderation pages are all rendered by a single Jinja2 template h/templates/groups/create_edit.html.jinja2:

h/h/templates/groups/create_edit.html.jinja2

Lines 1 to 26 in 052e9e1

	{% extends "h:templates/layouts/group.html.jinja2" %}
	{% block styles %}
	{{ super() }}
	{# Avoid a "flash of unstyled content" by preloading the stylesheets that
	will be used by the Preact app within its Shadow DOM. #}
	{% for url in asset_urls('group_forms_css') %}
	<link rel="preload" href={{ url }} as="style" />
	{% endfor %}
	{% endblock %}
	{% block page_content %}
	<div class="form-container form-container--wide">
	<div id="group-form"></div>
	<script type="application/json" class="js-config">{{ js_config|tojson }}</script>
	</div>
	{% endblock %}
	{% block scripts %}
	{{ super() }}
	{% for url in asset_urls('group_forms_js') %}
	<script type="module" src="{{ url }}"></script>
	{% endfor %}
	{% endblock %}

Of course the Jinja2 template doesn't render the actual contents of the page, those're rendered by a Preact app (see below). The Jinja2 template just injects the CSS and JS for the Preact app based on the assets bundles that were defined in assets.ini (more on how these assets bundles are defined below).

The Jinja2 template also renders a <script type="application/json" class="js-config"> object containing the Preact app's config settings in JSON:

<script type="application/json" class="js-config">{{ js_config|tojson }}</script>

CSS & Tailwind

The root file for the CSS is h/static/scripts/group-forms.css. You'll want to add another CSS file like this for the login/signup pages, or @robertknight & @acelaya might ask you to rename this one so it can be reused.

There's a Gulp task to compile the group-forms.css file. Again you'll want to add another task like this or rename this task so it can be reused:

h/gulpfile.js

Lines 30 to 32 in 052e9e1

	gulp.task('build-tailwind-css', () =>
	buildCSS(['./h/static/styles/group-forms.css'], { tailwindConfig }),
	);

Finally, there's an assets bundle in assets.ini to tell Pyramid about the CSS file. Again you'll want to add another of these or rename this one:

h/h/assets.ini

Lines 28 to 29 in 052e9e1

	group_forms_css =
	styles/group-forms.css

JavaScript & Preact

Each Preact app needs to be registered in rollup.config.js for module bundling. You'll want to add another line like this one or rename this bundle so that it can be reused:

h/rollup.config.js

Lines 48 to 49 in 052e9e1

	// Preact app for creating new private groups.
	bundleConfig('group-forms', 'h/static/scripts/group-forms/index.tsx'),

As with the CSS there's an assets bundle in assets.ini to tell Pyramid about the JS file. Again you'll want to add another of these or rename this one:

h/h/assets.ini

Lines 31 to 32 in 052e9e1

	group_forms_js =
	scripts/group-forms.bundle.js

The source code for the group forms is in h/static/scripts/group-forms/. You'll want to add a new folder h/static/scripts/login-forms/.

index.tsx is the file that bootstraps Preact, you'll want to have one of these:

h/h/static/scripts/group-forms/index.tsx

Lines 1 to 13 in 052e9e1

	import { render } from 'preact';
	import AppRoot from './components/AppRoot';
	import { readConfig } from './config';
	function init() {
	const shadowHost = document.querySelector('#group-form')!;
	const shadowRoot = shadowHost.attachShadow({ mode: 'open' });
	const config = readConfig();
	render(<AppRoot config={config} />, shadowRoot);
	}
	init();

config.ts handles reading the Preact app's configuration settings from the js-config object, you'll want one of these too. As you can see, it defines a lot of TypeScript types:

h/h/static/scripts/group-forms/config.ts

Lines 1 to 54 in 052e9e1

	import { createContext } from 'preact';
	import type { GroupType } from './utils/api';
	export type APIConfig = {
	method: string;
	url: string;
	headers: Record<PropertyKey, unknown>;
	};
	export type Group = {
	pubid: string;
	name: string;
	description: string;
	link: string;
	type: GroupType;
	num_annotations: number;
	pre_moderated: boolean;
	};
	export type ConfigObject = {
	/** The URLs of the app's CSS stylesheets. */
	styles: string[];
	api: {
	createGroup: APIConfig;
	updateGroup?: APIConfig;
	readGroupMembers?: APIConfig;
	editGroupMember?: APIConfig;
	removeGroupMember?: APIConfig;
	groupAnnotations?: APIConfig;
	};
	context: {
	group: Group | null;
	user: {
	userid: string;
	};
	};
	features: {
	group_members: boolean;
	group_type: boolean;
	group_moderation: boolean;
	};
	};
	/** Return the frontend config from the page's <script class="js-config">. */
	export function readConfig(): ConfigObject {
	try {
	return JSON.parse(document.querySelector('.js-config')!.textContent!);
	} catch {
	throw new Error('Failed to parse frontend configuration');
	}
	}
	export const Config = createContext<ConfigObject | null>(null);

Most of the actual code can be found in the components/ subdir (since a Preact app is mostly just a tree of components).

The <AppRoot/> component is the top-level one:

h/h/static/scripts/group-forms/components/AppRoot.tsx

Lines 16 to 59 in 052e9e1

	export default function AppRoot({ config }: AppRootProps) {
	const stylesheetLinks = useMemo(
	() =>
	config.styles.map((stylesheetURL, index) => (
	<link
	key={`${stylesheetURL}${index}`}
	rel="stylesheet"
	href={stylesheetURL}
	/>
	)),
	[config],
	);
	// Saved group details. Extracted out of `config` so we can update them after
	// saving changes to the backend.
	const [group, setGroup] = useState(config.context.group);
	return (
	<>
	{stylesheetLinks}
	<Config.Provider value={config}>
	<Router>
	<Switch>
	<Route path={routes.groups.new}>
	<CreateEditGroupForm group={group} onUpdateGroup={setGroup} />
	</Route>
	<Route path={routes.groups.edit}>
	<CreateEditGroupForm group={group} onUpdateGroup={setGroup} />
	</Route>
	<Route path={routes.groups.editMembers}>
	<EditGroupMembersForm group={group!} />
	</Route>
	<Route path={routes.groups.moderation}>
	<GroupModeration group={group!} />
	</Route>
	<Route>
	<h1 data-testid="unknown-route">Page not found</h1>
	</Route>
	</Switch>
	</Router>
	</Config.Provider>
	</>
	);
	}

<AppRoot/> is the component that index.tsx injects into the HTML:

h/h/static/scripts/group-forms/index.tsx

Line 10 in 052e9e1

render(<AppRoot config={config} />, shadowRoot);

The <Router> and <Route> stuff in AppRoot.tsx is how a single Preact app handles different pages depending on the URL, and can also handle navigations between URLs without doing full-page reloads. We use https://www.npmjs.com/package/wouter-preact for this.

From there, it's basically just a case of breaking <AppRoot/> down into separate sub-components in separate files, just because it would be too complicated if it was all one big component. As you can see, <AppRoot/> injects either <CreateEditGroupForm/> or <EditGroupMembersForm/> or <GroupModeration/> depending on the URL. These are all custom components defined in other files within the components/ dir.

Making API requests from JavaScript

We may not need to make any API requests for signup or login but just in case...

API requests from h's frontend code are authenticated using a secure, HTTPS-only, SameSite=Strict cookie plus a CSRF token. This is all set up already. There's a hard-coded list of API endpoints that the frontend is allowed to call. Any new endpoints that you want to call need to be added to this list.

There's a JavaScript API client in api.ts (will need to move this to another folder if it's to be called by more than just the group pages): https://github.com/hypothesis/h/blob/main/h/static/scripts/group-forms/utils/api.ts

JavaScript tests

Tests are done by unit testing one component at a time. For example for components/CreateEditGroupForm.tsx there's components/test/CreateEditGroupForm-test.js.

Some notes about the JavaScript tests:

• They're written in plain JavaScript, no TypeScript
• We have a repo of common testing utilities: https://github.com/hypothesis/frontend-testing
• Mocha is the test framework we use (the closest equivalent to pytest in our JavaScript test stack). Mocha provides the describe() and it() functions for writing tests. Also before(), after(), beforeEach() and afterEach() for setup and teardown.
• Unlike pytest, Mocha doesn't provide its own assertions (nor does JavaScript have a builtin assert keyword). We use Chai for writing assertions, and use Chai's assert-style API
• We use Sinon.JS for spies, stubs and mocks
• We use https://github.com/robertknight/babel-plugin-mockable-imports
• We use Enzyme for "mounting" Preact components in order to test them: https://enzymejs.github.io/enzyme/

[acelaya]

• Mocha is the test framework we use (the closest equivalent to pytest in our JavaScript test stack). Mocha provides the describe() and it() functions for writing tests. Also before(), after(), beforeEach() and afterEach() for setup and teardown.

We have migrated away from Mocha as part of the Karma-to-Vitest migration, as Vitest exposes the same globals that Mocha provides, so there's no longer a need for it.

The only difference is that before and aafter are called beforeAll and afterAll, and there's no context global, but we are currently aliasing it to describe in every project, so it can continue being used.

• Unlike pytest, Mocha doesn't provide its own assertions (nor does JavaScript have a builtin assert keyword). We use Chai for writing assertions, and use Chai's assert-style API
• We use Sinon.JS for spies, stubs and mocks

Technically speaking, Vitest does provide mechanisms to perform assertions and expectations, as well as for mocking, so we could also replace Chai and Sinon eventually. However, that's a lot of rewriting and we haven't even discussed it's that's the way we want to go.