django-components/docs/overview/development.md

title	weight
Development	7

Install locally and run the tests

Start by forking the project by clicking the Fork button up in the right corner in the GitHub. This makes a copy of the repository in your own name. Now you can clone this repository locally and start adding features:

git clone https://github.com/<your GitHub username>/django-components.git
cd django-components

To quickly run the tests install the local dependencies by running:

pip install -r requirements-dev.txt

You also have to install this local django-components version. Use -e for editable mode so you don't have to re-install after every change:

pip install -e .

Now you can run the tests to make sure everything works as expected:

pytest

The library is also tested across many versions of Python and Django. To run tests that way:

pyenv install -s 3.8
pyenv install -s 3.9
pyenv install -s 3.10
pyenv install -s 3.11
pyenv install -s 3.12
pyenv install -s 3.13
pyenv local 3.8 3.9 3.10 3.11 3.12 3.13
tox -p

To run tests for a specific Python version, use:

tox -e py38

NOTE: See the available environments in tox.ini.

And to run only linters, use:

tox -e mypy,flake8,isort,black

Running Playwright tests

We use Playwright for end-to-end tests. You will therefore need to install Playwright to be able to run these tests.

Luckily, Playwright makes it very easy:

pip install -r requirements-dev.txt
playwright install chromium --with-deps

After Playwright is ready, simply run the tests with tox:

tox

Developing against live Django app

How do you check that your changes to django-components project will work in an actual Django project?

Use the sampleproject demo project to validate the changes:

1. Navigate to sampleproject directory:

   cd sampleproject
   

2. Install dependencies from the requirements.txt file:

   pip install -r requirements.txt
   

3. Link to your local version of django-components:

   pip install -e ..
   

   !!! note

    The path to the local version (in this case `..`) must point to the directory that has the `setup.py` file.
   

4. Start Django server

   python manage.py runserver
   

Once the server is up, it should be available at http://127.0.0.1:8000.

To display individual components, add them to the urls.py, like in the case of http://127.0.0.1:8000/greeting

Building JS code

django_components uses a bit of JS code to:

• Manage the loading of JS and CSS files used by the components
• Allow to pass data from Python to JS

When you make changes to this JS code, you also need to compile it:

1. Make sure you are inside src/django_components_js:

   cd src/django_components_js
   

2. Install the JS dependencies

   npm install
   

3. Compile the JS/TS code:

   python build.py
   

   The script will combine all JS/TS code into a single .js file, minify it, and copy it to django_components/static/django_components/django_components.min.js.

Packaging and publishing

To package the library into a distribution that can be published to PyPI, run:

# Install pypa/build
python -m pip install build --user
# Build a binary wheel and a source tarball
python -m build --sdist --wheel --outdir dist/ .

To publish the package to PyPI, use twine (See Python user guide):

twine upload --repository pypi dist/* -u __token__ -p <PyPI_TOKEN>

See the full workflow here.

Development guides

Head over to Dev guides for a deep dive into how django_components' features are implemented.