Frontend¶
The Warehouse frontend is (as you might suspect) written in JavaScript with the
CSS handled by SCSS. It uses webpack
to process these files and prepare them for
serving.
All of the static files are located in warehouse/static/
and external
libraries are found in package.json
.
The static files are compiled and included in the
warehouse:docker-compose-static
Docker image.
Building¶
Static files should be automatically built when make serve
is
running; however, you can also manually run commands in the static
container:
$ # install dependencies
$ docker compose run --rm static npm install
$ # start a build
$ docker compose run --rm static npm run build
Building outside of Docker¶
Note: building outside of Docker is not recommended as it may install platform-specific dependencies.
Install NodeJS 20.x,
install the dependencies using npm install
and then run npm run
build
.
If you’re in a POSIX environment you may find NVM useful to have multiple NodeJS versions installed in your system.
Tests¶
The JavaScript codebase includes tests that can be ran via
make static_tests
. This target will run the static tests in the Docker
environment but they may also be ran locally using npm run test
once NodeJS
and the dependencies are installed as described above.
JavaScript tests use the Jest testing framework
along with jest-dom
for assertion helpers. We can invoke Jest directly specify a particular
test suite via node_modules/.bin/jest tests/frontend/<TEST_FILE>.js
or
add any of the Jest CLI options .
All tests are located in the tests/frontend
.
Stimulus controller tests leverage on Jest including JSDOM allowing us to inject the required HTML markup for Stimulus in a setup phase. After the setup we must manually instantiate and start a Stimulus application and then test the funcionality by triggering events in DOM elements and asserting on the effects. See existing tests the details on how to accomplish this.
Note
This workflow may cause race conditions, in particular when testing
code in the early lifecycle events of the controllers. The application or
controller may not be ready by the time we reach the assertions causing
false negatives on the tests. In these cases it’s best to keep the HTML
setup in a beforeEach
block, even if it means repeating the setup on
different describe
scenarios. This will ensure the application and
controllers are ready before the actual test is ran.
Deploying¶
When deploying changes to the frontend, to see the changes immediately it is necessary to purge the cache.
Individual pages can be purged from the command line by issuing a XPURGE
request, e.g.:
curl -XPURGE https://pypi.org/the/page/to/purge
All HTML pages can be dropped from the cache by purging the all-html
surrogate key via our CDN provider.
The entire cache can be purged by issuing a “Purge All” via our CDN provider.
Purging the cache is not usually necessary when making frontend changes, unless it would be unacceptable for the site to simultaneously have an “old” version of some pages, but the “new” version of others.
Browser Support¶
We aim to support all major browsers. We also support one-back,
and follow the defaults
recommendation from browserslist
.
You can see the full list of supported browsers by running npx browserslist
in the root of the project.
HTML Code Style¶
Warehouse follows the Google HTML style guide, which is enforced via linting with HTML Linter.
Exceptions to these rules include:
Protocols can be included in links - we prefer to include
https
protocolsAll HTML tags should be closed
We also allow both dashes and underscores in our class names, as we follow the Nicholas Gallagher variation of the BEM naming methodology.
More information on how BEM works can be found in this article from CSS Wizardry.
When using target="_blank_"
for a hyperlink (usually to an external site),
we should always set rel="noopener"
.
SCSS Style and Structure¶
Warehouse follows the Airbnb CSS/Sass style guide,
with the exception that JS hooks should be prefixed with -js
rather
than js
.
Our SCSS codebase is structured according to the ITCSS system. The principle of this system is to break SCSS code into layers and import them into a main stylesheet in an order moving from generic to specific. This tightly controls the cascade of styles.
The majority of the SCSS styles are found within the ‘blocks’ layer, with each BEM block in its own file. All blocks are documented at the top of the file to provide guidelines for use and modification.
One of these blocks provides code syntax highlighting, which can be tested with reference project provided at http://localhost/project/pypi-code-highlighting-demo/ when using development database. Source reStructuredText file is available here.