Development

Working with templates

Default storefront templates are based on Bootstrap 4.

You can find the files under /templates/.

Working with front-end assets

All static assets live in subdirectories of /saleor/static/.

Stylesheets are written in Sass and rely on postcss and autoprefixer for cross-browser compatibility.

JavaScript code is written according to the ES2015 standard and relies on Babel for transpilation and browser-specific polyfills.

Everything is compiled together using webpack module bundler.

The resulting files are written to /saleor/static/assets/ and should not be edited manually.

During development it’s very convenient to have webpack automatically track changes made locally. This will also enable source maps that are extremely helpful when debugging.

To run webpack in watch mode run:

$ npm start

Warning

Files produced this way are not ready for production use. To prepare static assets for deployment run:

$ npm run build-assets --production

Working with backend code

Python dependencies

To guarantee repeatable installations all project dependencies are managed using pip-tools. Project’s direct dependencies are listed in requirements.in and running pip-compile generates requirements.txt that has all versions pinned.

We recommend you use this workflow and keep requirements.txt under version control to make sure all computers and environments run exactly the same code.

Running tests

Before you make any permanent changes in the code you should make sure they do not break existing functionality.

The project currently contains very little front-end code so the test suite only covers backend code.

To run backend tests use pytest:

$ py.test

You can also test against all supported versions of Django and Python. This is usually only required if you want to contribute your changes back to Saleor. To do so you can use Tox:

$ tox

Continuous integration

The storefront ships with a working CircleCI configuration file. To use it log into your CircleCI account and enable your repository.

Docker

Using Docker to build software allows you to run and test code without having to worry about external dependencies such as cache servers and databases.

Warning

The following setup is only meant for local development. See Docker for production use of Docker.

You will need to install Docker and docker-compose before performing the following steps.

To build assets you will need node and webpack module bundler.

Note

Our configuration exposes PostgreSQL, Redis and Elasticsearch ports. If you have problems running this docker file because of port conflicts, you can remove ‘ports’ section from docker-compose.yml

  1. Install JavaScript dependencies

    $ npm install
    
  2. Prepare static assets

    $ npm run build-assets
    
  3. Build the containers using docker-compose

    $ docker-compose build
    
  4. Prepare the database

    $ docker-compose run web python manage.py migrate
    $ docker-compose run web python manage.py collectstatic
    $ docker-compose run web python manage.py populatedb --createsuperuser
    

    The --createsuperuser switch creates an admin account for admin@example.com with the password set to admin.

  5. Run the containers

    $ docker-compose up
    

By default, the application is started in debug mode, will automatically reload code and is configured to listen on port 8000.