django-deno

Deno front-end integration for Django, version 0.2.0.

rollup.js - bundling for Django packages static files with importmap resolver.
sucrase - optional TypeScript support.
terser - optional compression of bundles.
The deno server may be extended to support any of deno api, when applicable.
Uses parts of drollup code, refactored for Deno v2.

Requirements

Deno 2.0.6 or newer.
Django 4.2 / Django 5.1 was tested with continuous integration demo app djk-sample.

Installation

In Ubuntu Linux:

curl -fsSL https://deno.land/install.sh | sh
export DENO_INSTALL=$HOME/.deno

In Windows run PowerShell then invoke:

irm https://deno.land/install.ps1 | iex
set DENO_INSTALL=%userprofile%\.deno

DENO_INSTALL environment variable specifies directory where Deno is installed.

In case currently installed Deno version is older than 2.0.6, please use deno upgrade command to install the newer Deno version. Deno 1.x is supported only with django-deno versions lower than 0.2.0.
This package was tested with Deno version 2.0.6:
```
deno upgrade --version 2.0.6
```

The package may work with newer versions of Deno, however it was not tested, thus may fail.

However, since v0.2.0 there is precompiled binary for Linux available, which allows to have stable running environment, see deno_compile management command.

To install the development version of django_deno in python3 virtualenv:

pip install -U git+https://github.com/Dmitri-Sintsov/django-deno.git

To install the stable version of django_deno in python3 virtualenv:

pip install -U git+https://github.com/Dmitri-Sintsov/django-deno.git@v0.2.0

Description

django_deno installs Deno web service which is used to communicate with Django projects.

Currently the web service server.ts supports Deno version of rollup.js bundler to automatically generate es6 modules bundles for Django projects, including scripts from Django packages static files.

It's possible to generate es6 modules bundles and / or systemjs bundles with optional minification with terser.

Transpiling of TypeScript is supported with sucrase. When sucrase is not enabled, it's expected that the developing code has es6 imports / exports but the rest of code is written with es5 syntax.

At Django side django_deno provides the following Django management commands:

collectrollup

collectrollup - similar to Django collectstatic command, but uses rollup.js to generate Javascript bundles.

It's preferable to run the collectrollup command this way from the Django project virtualenv:

python3 manage.py collectrollup --clear --noinput

--clear option is suggested because the target output may vary depending on the source scripts.

There is djk-sample script for running collectrollup in Linux:

#!/bin/sh
DJANGO_DEBUG='False' python3 $VIRTUAL_ENV/djk-sample/manage.py collectrollup --noinput --clear

https://github.com/Dmitri-Sintsov/djk-sample/blob/master/cli/collectrollup.sh

in Windows:

if not defined DENO_INSTALL (
    set DENO_INSTALL=%USERPROFILE%\.deno
)
set "DJANGO_DEBUG=False" & python %VIRTUAL_ENV%/djk-sample/manage.py collectrollup --noinput --clear

https://github.com/Dmitri-Sintsov/djk-sample/blob/master/cli/collectrollup.cmd

The script also sets the environment variable DJANGO_DEBUG to False which is parsed in djk-sample settings.py:

DEBUG = os.environ.get('DJANGO_DEBUG', 'true').lower() in TRUE_STR

to set the value of DENO_OUTPUT_MODULE_TYPE which determines the type of Javascript modules generated, either module for modern browsers that support es6 natively, or SystemJS modules, which are compatible with IE11:

# Do not forget to re-run collectrollup management command after changing rollup.js bundles module type:
DENO_OUTPUT_MODULE_TYPE = 'module' if DEBUG else 'systemjs-module'

The additional settings for rollup.js running collectrollup management command are specified with DENO_ROLLUP_COLLECT_OPTIONS setting, which allows to enable / disable terser compression and to enable / disable sucrase transpiling of TypeScript:

# Run $VIRTUAL_ENV/djk-sample/cherry_django.py to check the validity of collectrollup command output bundle.
DENO_ROLLUP_COLLECT_OPTIONS = {
    'sucrase': True,
    'terser': True,
}

while the default is:

DENO_ROLLUP_COLLECT_OPTIONS = {
    # 'relativePaths': True,
    'staticFilesResolver': 'collect',
    'sucrase': True,
    'terser': True,
    'bundles': getattr(settings, 'DENO_ROLLUP_BUNDLES', {}),
    'moduleFormat': DENO_OUTPUT_MODULE_FORMATS[DENO_OUTPUT_MODULE_TYPE],
    'syntheticNamedExports': getattr(settings, 'DENO_SYNTHETIC_NAMED_EXPORTS', {}),
}

syntheticNamedExports allows to specify the list of synthetic named exports for es6 modules manually, e,g:

DENO_SYNTHETIC_NAMED_EXPORTS = {
    'document.js': 'ActionTemplateDialog, Actions, Dialog, Grid, GridActions, GridRow, globalIoc, inherit, ui, TabPane',
}

See the complete default settings: django_deno settings

runrollup

runrollup - starts the built-in http development server, similar to Django runserver command, using rollup.js to dynamically generate Javascript bundle in RAM, providing real-time es6 modules compatibility for older browsers and TypeScript compatibility for newer browsers.

Set DENO_ROLLUP_SERVE_OPTIONS for the rollup.js options of the runrollup command. The default is:

DENO_ROLLUP_SERVE_OPTIONS = {
    'inlineFileMap': True,
    # 'relativePaths': True,
    'sucrase': True,
    'preserveEntrySignatures': False,
    'staticFilesResolver': 'serve',
    'withCache': True,
}

When staticFilesResolver is set to serve, getStaticFilesResolver is used to resolve Django packages static files at Deno side via automatically generated import maps.

deno_compile

deno_compile - compiles built-in server.ts to django_deno binary file with deno compile for the package distribution. This management command allows to have stable production running environment. Since v0.2.0 it's a preferred way to perform vendoring / bundling of the package.
Binary compression is supported via --compress option. github hosted compressed django_deno.lzma binary can be downloaded and extracted automatically, with the following settings.py value:
```
DENO_USE_COMPILED_BINARY = True
```

deno_install

deno_install management command generates updated deno install bundle for the built-in deno server. This command should be used only for the package updating / redistribution.
Since Deno v2, it seems to impossible to create the source bundle without remote dependencies (see denoland/deno#26488). Thus deno_compile currently is the preferred way to perform vendoring / bundling of the package.

Updating deno_install should be performed with the following steps:

Run the project collectrollup command with the following settings.py to reload the dependencies:
```
DENO_USE_VENDOR = False
DENO_RELOAD = True
DENO_CHECK_LOCK_FILE = False
```
Run the project deno_install command to create local deno install:
```
python3 manage.py deno_install
```
Run the project collectrollup command with the following settings.py, to use the updated local deno_install:
```
DENO_USE_VENDOR = True
DENO_RELOAD = False
DENO_CHECK_LOCK_FILE = True
```

Bundles

Creation of rollup.js bundles has two steps, first one is the definition of Entry points, second is the definition of Chunks. Both are specified in Django project settings.py.

Entry points

At the first step, one has to specify Javascript entry points with DENO_ROLLUP_ENTRY_POINTS setting, for example djk-sample settings:

DENO_ROLLUP_ENTRY_POINTS = [
    'sample/js/app.js',
    'sample/js/club-grid.js',
    'sample/js/member-grid.js',
]

These are the top scripts of es6 module loader hierarchy.

Alternatively, the script may specify use rollup directive at the first line of Javascript code, which is used for Django packages entry points and is discouraged for project entry points.

Chunks

To specify manual bundles / chunks, DENO_ROLLUP_BUNDLES setting is used. For example djk-sample settings:

DENO_ROLLUP_BUNDLES = {
    'djk': {
        'writeEntryPoint': 'sample/js/app.js',
        'matches': [
            'djk/js/*',
            'djk/js/lib/*',
            'djk/js/grid/*',
        ],
        'excludes': [],
        'virtualEntryPoints': 'matches',
        'virtualEntryPointsExcludes': 'excludes',
    },
}

djk key specifies the chunk name which will result in generation of djk.js bundle.
writeEntryPoint key specifies main entry point, which is used to generate djk.js bundle. djk.js bundle is shared among the some / all of Entry points, reducing code redundancy.
matches key specifies the list of matching dirs which scripts that will be included into djk.js bundle.
excludes specifies the list of scripts which are excluded from the djk.js bundle.
virtualEntryPoints specifies either the list of dirs or matches string value to set es6 modules virtual entry points. Such modules are bundled as a virtual ones, included into djk.js bundle only, not being duplicated as separate standalone module files. See isVirtualEntry / setVirtualEntryPoint code for more info.
To see the actual settings / usage, demo apps djk-sample and drf-gallery are available.