DocumentCloud Frontend · Squarelet · MuckRock · DocumentCloud
The main frontend for DocumentCloud, written in SvelteKit.
This project depends on both Squarelet and the DocumentCloud (Django). Follow the steps in their READMEs before setting up this project.
In order to install dependencies inside the Docker container and on your host machine, run:
make installOnce the node modules have been installed, start the app with:
make devSet up your hosts:
echo "127.0.0.1 www.dev.documentcloud.org" | sudo tee -a /etc/hostsOnce everything is up and running, you should be able to see the website live at www.dev.documentcloud.org.
Run make build to build the production version of the app. The project will be output in the build directory. (This happens on Netlify and during Github Actions automatically.)
DocumentCloud is tested and runs on recent versions of modern browsers -- Chrome, FireFox, Safari and Microsoft Edge. Older versions of those browsers will likely work, too, but we can't guarantee a bug-free experience on versions from more than a year ago, or on browsers that no longer receive updates, such as Internet Explorer.
- Use
process.envfor things running on a development machine in a Node context, like Vite configs and other dev or build scripts. - In SvelteKit:
- In a server context, you can use
import {env} from "$env/dynamic/privateto access variables defined inprocess.env. - In a client context, you can only
import {env} from "$env/static/publicto access variables named with aPUBLIC_prefix.
- In a server context, you can use
Learn more about using environment variables in the SvelteKit learning docs.
Run the relevant npm install ... command and then get the change mirrored on the Docker image by running make install.
Run unit tests with npm run test:unit. Running npm run test:watch will re-run tests as code changes.
We use snapshots for testing component rendering. After updating Svelte components or styles, snapshot tests may fail if they're not updated. To update snapshots, run npm run test:unit -- -u.
All of the browser test commands depend on the front end running, so start the app with make dev and start the backend and Squarelet as well.
Run npm run test:browser in another terminal. This will run Playwright using Chromium and Firefox.
The functional tests are colocated with the files they test, like this:
src/lib/api/
├── accounts.ts
├── addons.ts
├── collaborators.ts
├── documents.ts
├── embed.ts
├── feedback.ts
├── flatpages.ts
├── notes.ts
├── projects.ts
├── sections.ts
├── tests
│ ├── accounts.test.ts
│ ├── addons.test.ts
│ ├── collaborators.test.ts
│ ├── documents.test.ts
│ ├── embed.test.ts
│ ├── flatpages.test.ts
│ ├── notes.test.ts
│ ├── projects.test.ts
│ └── sections.test.ts
└── types.d.ts
Component tests use the Svelte Testing Library and are also colocated near the components they test, usually in a tests folder.
Earlier interations of DocumentCloud used scripts to inject the viewer, pages and notes into other web pages. This approach has been deprecated in favor of iframe-based embeds, but lots of legacy embeds exist across the internet. To support these older embeds, we've rewritten the original scripts to inject an iframe where appropriate.
These scripts live in the src/embeds directory and are built with esbuild. They're not part of the larger SvelteKit project, so they have a separate build process that may change later. (Our main build tool, Vite, also depends on esbuild.)
Storybooks are used to create isolated environments for developing, testing and demonstrating the Svelte components that compose the user interface.
Storybooks run locally to your machine, not in the Docker container.
To run the Storybook dev server:
npm run storybookTo set and manage your Node version, you can use NVM or nodenv:
node -v
nvm install 20
# or
nvm install --lts
Thanks to Chromatic for providing the visual testing platform that helps us review UI changes and catch visual regressions.