Hello Deno!

An opinionated deno project starter template.

This template provides examples and a batteries included experience for starting a new project in Deno land.

$ just all

Features

Sane VSCode defaults for deno
Benchmarking example
Compiled executable example
Testing example
Vendoring capabilities
NPM Compatibility
Deno confiugration
Import Map usage example
Standard MIT Licence
Executable entry point (main.ts)
Library entry points (mod.ts)

Requirements

Install guide

Deno VSCode Extension

code --install-extension denoland.vscode-deno

Manual

https://deno.land/manual/vscode_deno

Deno

Refer to deno manual installation

Just

Refer to just packages installation

Note: Windows users, please use git-bash to interact with just

Structure

.vscode VSCode configurations
- extensions.json VSCode extensions
- settings.json VSCode settings
bin/ deno compile output
- build_npm_package.ts transforming for npm with dnt
- deno.json using deno.json config file
- import_map.json using import_map.json
- lock.json lockfile
- vendor Vendored dependencies
hello_bench.ts deno bench example
hello_test.ts deno test example
justfile Justfile for running tasks
LICENCE default MIT licence
main.ts compilation entry-point main.ts
mod.ts library entry point mod.ts

Justfile

Dependencies and Tasks

Tasks can be considered the equivalent of npm scripts. Deno counterpart exposes deno task command, and it's not ideal to write your tasks in deno.json config. Therefore the author's best current advice is just using a makefile. The sections are organized into Chores and Tasks.

Configuration

`dev_flags`

dev_flags = --unstable -A -c ./deno.json

Default run flags:

Enabling Deno Unstable APIs
allowing All Permissions.
Setting Deno Conifg path

`prod_flags`

prod_flags = --check --cached-only --no-remote --import-map=vendor/import_map.json --lock ./lock.json

Production flags:

always type-check (tsc)
use only cached deps
no remote dependencies allowed
point to vendored import-map always
validate dependencies against lock file

Locking settings, defining the lock file.

`dep_flags`

dep_flags = --import-map ./import_map.json --lock ./lock.json

Dependency flags:

use import map to resolve dependencies
use/write lock file to ./lock.json

`test_files`

Path to test files (e.g. ./*_test.ts)

`source_files`

Path to source files, default is any file in the root, (e.g. ./*.ts)

`all_files`

all_files = "./*.ts ./node/*.ts"

Source + Test files.

`udd`

udd = deno run -A https://deno.land/x/udd@0.7.3/main.ts

Alias for UDD library. Used for automatically updating dependencies.

Most important commands

just chores: Update dependencies, write lock file, reload cache, vendor dependencies and load them into cache.
just build: Build bin, lib and npm package.
just: chores && build

Dependencies

Modules are typically registered in the import-map.

Check for updates

update:
    $(udd) main.ts $(dep_flags) --test="make test"
    make deps

Look over import_map and dependency tree stemming from main.ts entry-point and update them to latest versions.

deps: lock reload vendor cache

Reload dependency tree without updating it.

Lock when you add new dependencies

lock:
    deno cache $(dep_flags) --lock-write $(source_files)

Produce a lock file of the dependency tree.

Reload cache

reload:
    deno cache -r $(dep_flags) $(source_files)

Reload local cache.

Vendor the dependencies

Import map overridden as config sets the vendored import-map. Obviously the vendoring can't depend on the import map it outputs.

vendor: 
    deno vendor $(dep_flags)  --force $(source_files)

Vendor dependencies for production builds.

Cache the locked dependencies

cache:
    deno cache $(lock_flags) $(source_files)

Populate local cache from vendored dependencies for all source files.

Tasks

Run the benchmark(s)

Benchmarks end in `_bench.ts`

bench: clean
    deno bench $(run_flags)

Run benchmarks.

Build the bin

build-bin: cache
    deno compile -o bin/hello_deno --import-map vendor/import_map.json $(run_flags) ./main.ts

Compile into a single executable.

Build for NPM

build-npm:
    deno run -A ./build_npm_package.ts $$VERSION

Build a package to be published on npm.

clean:
    rm -rf bin npm

Clean previously built artifacts.

Publish the npm module from CI

publish: deno build-npm
    cd npm && npm publish

Release to NPM.

Profiling

debug:
    deno run --v8-flags=--prof --inspect-brk $(run_flags) bench/run_suite.ts

Debug

Linting

lint:
    deno lint $(all_files)

Run linter.

Formatting

format:
    deno fmt $(all_files) $(docs)

Run formatting.

Testing

test: clean
    deno test $(run_flags) --coverage=cov_profile $(test_files)
    deno test $(run_flags) --doc mod.ts

Run tests.