DocumentCloud frontend
DocumentCloud Frontend · Squarelet · MuckRock · DocumentCloud
The main frontend for DocumentCloud, written in SvelteKit.
Usage
Local Stack
It's possible to run all the dependencies for this project completely locally, as long as you already have both Squarelet and the DocumentCloud (Django) running in Docker containers. 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 install
Once the node modules have been installed, start the app with:
make dev
Set up your hosts:
echo "127.0.0.1 www.dev.documentcloud.org" | sudo tee -a /etc/hosts
Once everything is up and running, you should be able to see the website live at www.dev.documentcloud.org.
Remote Stack
It's possible to run the frontend against the staging API, instead of a locally running API server, providing a lightweight solution for local development. The frontend needs to run on a custom localhost, https://local.staging.documentcloud.org, and is exposed on the standard 5173 port used by Vite dev servers.
To run the dev server locally against the staging API, take the following steps:
- Update your hosts file
echo "127.0.0.1 local.staging.documentcloud.org" | sudo tee -a /etc/hosts
- Make a local certificate in a
certs directory
mkdir certs && cd certs
mkcert -install
mkcert local.staging.documentcloud.org
- Use NPM to install and run the
dev:remote script
npm install
npm run dev:remote
Now, you should have a dev server accessible at https://local.staging.documentcloud.org:5173 that connects to the staging DocumentCloud API (https://api.staging.documentcloud.org) and staging authentication service (https://staging-accounts.muckrock.com).
Building for production
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.)
Browser support
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.
Environment Variables
- Use
process.env for 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/private to access variables defined in process.env.
- In a client context, you can only
import {env} from "$env/static/public to access variables named with a PUBLIC_ prefix.
Learn more about using environment variables in the SvelteKit learning docs.
Trending documents (Cloudflare analytics)
The homepage shows a "Trending documents" list powered by the Cloudflare GraphQL Analytics API. It reads two server-only variables:
CLOUDFLARE_ANALYTICS_TOKEN — a Cloudflare API token with Account Analytics: Read permission. Store it as a Worker secret (see docs/cloudflare.md); never commit it.CLOUDFLARE_ANALYTICS_ACCOUNT_TAG — the Cloudflare account ID (a 32-character hex string), not a domain name. Find it under the API heading in the sidebar of the documentcloud.org site in the Cloudflare dashboard, or via curl -H "Authorization: Bearer $TOKEN" "https://api.cloudflare.com/client/v4/zones?name=documentcloud.org" (the account.id field).
We query the Web Analytics (RUM) rumPageloadEventsAdaptiveGroups dataset, which records real browser page loads, and filter to /documents/% paths server-side. The zone-level HTTP request dataset is not usable here: it counts every request on the zone, so the most-requested paths are static assets and document sub-resources (.pdf, .txt.json) rather than documents anyone actually viewed. The same query powers the top-daily-docs Add-On.
When either variable is missing (e.g. in local dev), the homepage gracefully falls back to the static featured-projects list, so these are optional for local development.
Local development: analytics come from production traffic, but npm run dev points at the dev API (api.dev.documentcloud.org), which does not have those production documents. The trending list will therefore be empty locally even when both variables are set, and the page falls back to featured projects. To exercise it end to end, run PUBLIC_ENV=production npm run dev — the API base is selected by PUBLIC_ENV in src/config/config.js, so setting PUBLIC_DC_BASE has no effect. Note this also repoints auth and embeds at production, so treat it as a verification mode.
Staging analytics cannot substitute: staging.documentcloud.org sees only a handful of page loads, and its document traffic is Playwright e2e fixtures that are deleted after each run.
Zendesk
In-app feedback opens a ticket in Zendesk, which needs three private variables:
ZENDESK_SUBDOMAIN — the account subdomain, e.g. documentcloud for documentcloud.zendesk.comZENDESK_EMAIL — the email address of the agent whose API token we useZENDESK_API_TOKEN — an API token from Admin Center → Apps and integrations → Zendesk API
Without them, feedback submissions fail with a "Zendesk is not configured" error.
以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗
