djnext

djnext copied to clipboard

Django-NextJS

Isomorphic_ UI Development with Decorator_ pattern for Django_ with:

- NextJS_ out of the box experience for perfect frontend development,
- Django support for NextJS_ template rendering for perfect backend
  development,

Run the example project
=======================

Run this commands as non root:

.. code-block:: bash

    git clone https://git.yourlabs.org/oss/djnext
    cd djnext  # all commands must be executed from repo root
    pip install --user --editable .[dev]
    yarn install
    djnext djnext  # required for yarn dev to run
    yarn dev  # run localhost:3000
    djnext dev  # run localhost:8000

The purpose of the example project is to show a create form and a list page
with a hardcoded menu. For complete CRUD views, autogenerated menus and so on,
use CRUDLFA+.


Install in your project
=======================

Install NextJS
--------------

In your repo root, install NextJS_ which means adding these dependencies::

    yarn add nextjs react react-dom

And this commands to your package.json:

.. code-block:: js

    "scripts": {
      "dev": "next",
      "build": "next build",
      "start": "next start"
    }

Then you can run ``yarn dev``.

That was the first step of the NextJS_ tutorial.

Install DjNext
--------------

- Install djnext with pip for example: ``pip install --user djnext``
- Then, add urls for ``/_next``: ``path('_next', include('djnext.urls'))``,
- Then add ``djnext`` to ``INSTALLED_APPS``.
- Run ``manage.py djnext``

It will automatically setup the template backend if you haven't yourself. This
allows picking up React_ templates in JS from django.

While you run ``yarn dev``, you also need to run the ``djnext`` management
command to maintain the NextJS_ pages directory with the ``static/pages``
directory of every INSTALLED_APPS.

This will watch ``static/pages`` directories of all apps in INSTALLED_APPS, and
build the ``pages/`` directory, so that yarn dev will find it.

If you want to setup the template backend yourself and override options you can
do as such:

.. code-block:: python

    TEMPLATES = [
        {
            'BACKEND': 'djnext.backend.Backend',
            'OPTIONS': {
                'NEXTJS_DSN': 'http://localhost:3000',  # default: from env var
                'context_processors': [
                    'djnext_example.artist.context_processors.menu',
                ]
            },
        }
    ]

The above adds a context processor that will recieve the request as first
argument if the django-threadlocals middleware is installed, otherwise None. In
return, the context processor function must return a dict that will be merged
to the template context before being serialized and sent to the NextJS_ server.

Tutorial
========

NextJS template engine
----------------------

Example project lives in src/djnext_example, see ``src/djnext_example/artist/urls.py``:

.. code-block:: python

    CreateView.as_view(
        model=Artist,
        fields=['name'],
        success_url=reverse_lazy('artist_list'),
        template_name='create.js',
    )

The template backend queries the NextJS_ render server, because the djnext
command exposed ``components/*js`` and ``pages/*js`` from your INSTALLED_APPS
to NextJS_.

.. note:: For development, you need both ``yarn dev`` and ``manage.py djnext``.

Troubbleshooting
----------------

Try ``rm -rf node_modules .next pages && yarn install && manage.py
djnext & yarn dev`` to start the NextJS server from a fresh install.

Authors
=======

- Frontend research: Thomas Binetruy <[email protected]>
- Backend research: James Pic <[email protected]>

.. _NextJS: https://nextjs.org
.. _Django: https://www.djangoproject.com
.. _Isomorphic: https://en.wikipedia.org/wiki/Isomorphic_JavaScript
.. _Decorator: https://en.wikipedia.org/wiki/Decorator_pattern