Starter Kit

An example repository for building client libraries in Deno.

The work is not completely finished, but this repository demonstrates one possible workflow for getting:

• TypeScript generation in the browser
• CSS generation
• Hot reloading

With no dependencies other than Deno's std library, and our own @gdquest/toolbox library.

This project is for demonstration purposes, and you shouldn't see it as a rigid guide. The code was kept as simple as possible on purpose, and files commented so you can understand if you need them.

Purpose

We need to author client libraries. We want to do it in Deno, and ideally without any external dependencies.

Why Deno?

Deno allows us to:

• Write TypeScript without complicated setups
• Access good abstractions for dealing with the filesystem

So we want to also use it in the client, so we can write code in a style that is consistent and counting on the same runtime.

Why no dependencies?

We do want a convenient workflow, but we want as few dependencies as possible. NPM is overrun with malware, but besides that, my belief is that semver has failed, and the experiment of many dependencies has failed, even if there wasn't any malware.

On any large project, the time spent wrangling dependencies is a significant time sink that leaves projects worse, slower, harder to maintain, more brittle; that aside from more open to attacks by virtue of both presenting a common interface for hackers and supply chain attacks.

Ideally, we want to count only on Deno and the std library, and our own @gdquest/toolbox library, which we maintain. Any additional dependency should be duly considered.

General Structure:

• src/: the source code
• scripts/: build and deployment scripts
• preview/: the preview files for running the app in the client

File naming convention:

• *.web.ts: web-specific code (runs in the browser)
• *.server.ts: server-specific code (runs on the server)
• *.both.ts: shared code (runs on both the browser and the server)

Web files may be used on the server, provided they either:

• do not use DOM APIs
• provide a server-compatible alternative (or a no-op when it makes sense)

Server files may never be used in the client, as they may contain secrets or other sensitive data.

"Both" files should only use other "both" files, not "web" or "server" files; loading client files may be more convenient in some cases; this is to be decided on a case by case basis. However, "both" files should never load "server" files directly (otherwise they become server files themselves).

TLDR:

• *.web.ts: can use *.both.ts and *.web.ts files (but not *.server.ts files)
• *.server.ts: can use *.both.ts and *.server.ts files (but not *.web.ts files)
• *.both.ts: can use *.both.ts files; *.web.ts can be accepted when that simplifies the code; never *.server.ts files.

How to use the hot reload server

Run deno task dev to start the hot reload server.

Then change files. That's it!

I noticed two problems:

1. When you change the CSS, the page reloads, but can't load anything and says "server not responding". A manual refresh is required.
2. Sometimes, the page won't reload automatically. I wasn't able to determine exactly when.

Both those problems are probably trivial to fix, but I haven't taken the time as this is a repository for demonstration purposes, and fixing the problems specific to this example isn't strictly necessary, unless it's a recurrent problem that affects every project. We'll see.

Testing

For testing, we use preferentially Documentation tests

Exploit the documentation tests to write as many tests as possible, and try to use that as documentation for the code.

If the tests become too large or require a lot of dependencies to run, consider extracting tests to their own file.

Run deno task test to run all tests.

Commands

• deno task dev: run the development server
• deno task build: build the app
• deno task test: run all tests