Metadata-Version: 2.4
Name: django-npm-dev
Version: 0.1.0
Summary: django management command to launch npm run dev and manage.py runserver in one shot
Author: Geoff Beier
Author-email: Geoff Beier <geoff@tuxpup.com>
License-Expression: MIT
License-File: LICENSE.md
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# django_npm_dev

When you're using a tool like [vite](https://vite.dev), [webpack](https://webpack.js.org), or even just [TailwindCSS and PostCSS](https://tailwindcss.com/docs/installation/using-postcss) to package frontend assets that require a build step with your Django site, you frequently need to start a separate development server using `npm run dev` whenever you're using the Django development server to work locally.

`django_npm_dev` provides a Django management command that starts that npm dev server in a separate thread and then starts Django's development server. Stopping Django's development server in any of the usual ways will also stop the npm dev script.

Frequently, I'm happy to just use a [bash script like this one](https://github.com/saaspegasus/django-vite-tailwind-starter/blob/main/scripts/dev.sh). When I need to hand a project to someone who works on Windows, though, that becomes a challenge. I also find that IDEs (and especially their built-in debuggers) work more smoothly with Django management commands than they do with shell scripts, in my experience.

## Installation and Usage

Add `django-npm-dev` to your project using `pip` or your favorite package management tool.

```sh
pip install django-npm-dev
```

```sh
uv add django-npm-dev
```

Then add `django_npm_dev` to your `INSTALLED_APPS` in your site's `settings.py`

```python
INSTALLED_APPS = [
    ...,
    'django_npm_dev',
    ...,
]
```

Now, instead of running `python manage.py runserver` to start your local development server, run `python manage.py dev runserver`.

## Tips

If you're using Vite, and you make changes to django templates in addition to assets built by Vite, you should use install [`django-browser-reload`](https://github.com/adamchainz/django-browser-reload) so that django template changes trigger a reload as well as changes to Vite-managed assets.

---

If NPM isn't on your path, specify the path to your NPM command in settings.py:

```python
NPM_BIN_PATH=/opt/local/bin/npm
```

## Credits

Reading Cory Zue's [article about using Vite with Django](https://www.saaspegasus.com/guides/modern-javascript-for-django-developers/integrating-javascript-pipeline-vite/) and his comment when I suggested that this might fit with [the starter he published as a companion](https://github.com/saaspegasus/django-vite-tailwind-starter) made me think it belonged in its own package.

The NPM wrapper is an adapted version of the one [from django-tailwind](https://github.com/timonweb/django-tailwind).

## License

All original code in this repository is copyright 2025 Geoff Beier <geoff@tuxpup.com>. It's offered under the same [MIT LICENSE](LICENSE) as the NPM wrapper that I adapted from django-tailwind. Any other code distributed with this repository remains under copyright by its authors, and is used under their respective licenses.
