Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
152 lines (101 loc) · 3.27 KB

CONTRIBUTING.md

File metadata and controls

152 lines (101 loc) · 3.27 KB
Raw

Contributing to django-nuxt

Thanks for your interest in contributing to django-nuxt.

Repository: https://github.com/jrutila/django-nuxt

Ways to contribute

  • Report bugs and unexpected behavior
  • Improve documentation and examples
  • Add tests for edge cases and regressions
  • Submit bug fixes and small enhancements

Development prerequisites

  • Python 3.10+ (3.12 recommended)
  • uv (Python package and environment manager)
  • Node.js 20+ (for Nuxt example app)
  • npm, pnpm, yarn, or bun (examples below use pnpm)

Local setup

  1. Fork and clone the repository.
  2. Create a virtual environment with uv.
  3. Install development dependencies with uv.

Example commands:

uv sync
uv sync --group dev

You can run Python commands through uv run ... without manually activating the virtual environment.

Running tests

From the repository root:

uv run runtests.py

Please run tests before opening a pull request.

Running the example projects

This repository currently contains the example/basic project.

Example 1: Development mode (Django + Nuxt dev server)

This is the main way to develop and verify integration behavior.

  1. Install Python dependencies for the example with uv:
cd example/basic
uv sync
  1. Install and run Nuxt app in one terminal:
cd example/basic/ui
pnpm install
pnpm dev
  1. Run Django in another terminal:
cd example/basic
uv run manage.py migrate
uv run manage.py runserver
  1. Create a superuser:
uv run manage.py createsuperuser
  1. Open http://127.0.0.1:8000/.

Nuxt runs on port 3000, and Django on port 8000.

Example 2: Generated static mode (with Nuxt dev server)

Use this to test production-like static output serving from Django.

  1. Generate Nuxt static files:
cd example/basic/ui
pnpm install
pnpm run generate
  1. In example/basic/basic/settings.py, ensure this is configured:
  • DJANGO_NUXT_SERVER_RUNNING = False
  1. Run Django:
cd example/basic
uv run python manage.py migrate
uv run python manage.py runserver

Example 3: Generated static mode with collected static and non-debug mode

Do steps 1 and 2 from Example 2.

  1. Run Django:

Set DEBUG=False in example/basic/basic/settings.py.

cd example/basic
uv run python manage.py collectstatic

Check that there is a _nuxt folder in the staticfiles directory (without the /static/ prefix). Add NuxtStaticUrls() to the urlpatterns in example/basic/basic/urls.py as we are serving the Nuxt files with runserver next. In production, you should not use NuxtStaticUrls() but configure the /_nuxt/ static file serving independently.

uv run python manage.py runserver
  1. Open http://127.0.0.1:8000/.

Pull request guidelines

  • Keep PRs focused and small when possible
  • Add or update tests for behavior changes
  • Update docs when behavior or API changes
  • Use clear commit messages describing the intent
  • Include a short test plan in PR description

Reporting issues

When reporting a bug, include:

  • Operating system and Python version
  • django-nuxt version
  • Minimal reproducible example
  • Expected behavior vs actual behavior
  • Relevant logs or traceback

Code of conduct

Please be respectful and constructive in all project interactions.