Development

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

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

pip install -r requirements-dev.txt

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

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:

Navigate to sampleproject directory:
```
cd sampleproject
```
Install dependencies from the requirements.txt file:
```
pip install -r requirements.txt
```
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.
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:

Make sure you are inside src/django_components_js:
```
cd src/django_components_js
```
Install the JS dependencies
```
npm install
```
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.