DocumentCloud Frontend · Squarelet · MuckRock · DocumentCloud
The main frontend for DocumentCloud, written in Svelte.
This project depends on both Squarelet and the DocumentCloud (Django). Follow the steps in their READMEs before setting up this project.
This project is a Svelte + Webpack project wrapped in Docker compose.
In order to install dependencies inside the Docker container, run:
make installOnce the node modules have been installed, start the app with:
make devWarning: Don't just run docker compose up like you would with some of the other repos. The containers listed in local.yml aren't intended to be run simultaneously.
Set 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. Note the frontend is not yet functional.
Run make build to build the production version of the app. The project will be output in the public directory.
See the Wiki for information on the DocumentCloud architecture.
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.
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 test.
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 organized like this:
tests
├── README.md
├── anonymous
│ ├── manager
│ │ └── app.spec.js
│ ├── pages
│ │ └── home.spec.js
│ └── viewer
│ └── document.spec.js
└── fixtures
├── Small pdf.pdf
├── development.json
├── production.json
├── staging.json
└── the-nature-of-the-firm-CPEC11.pdf
Tests are organized around major parts of the codebase -- manager, pages and viewer. Tests under anonymous don't use an authenticated user.
Tests rely on specific docouments available in each environment, which will have different URLs, so lists of known documents are provided in development.json, staging.json and production.json. Those correspond to the NODE_ENV environment variable.
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:
node -v
nvm install 16
# or
nvm install --lts
Thanks to Chromatic for providing the visual testing platform that helps us review UI changes and catch visual regressions.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent