django-components/docs/overview/development.md at aaeba99f54b206baed072ffd0572035ddf5118a7

mirror of https://github.com/django-components/django-components.git synced 2025-09-15 18:34:59 +00:00

* Move docs-folder form src to root

* Avoid mkdocs package / module name clash

* Update location of docs & add Windows compatibility

* Update requirements-docs

* Update generated file to current state

2024-12-03 12:32:21 +01:00

3.8 KiB

Raw Blame History

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

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 (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

Deep dive into how django_components' features are implemented.

3.8 KiB Raw Blame History