make-deno-edition

Make a deno edition of a npm package

Overview

Examples

Here is a list of all the packages that make-deno-edition has made compatible with Deno.

The Need

Unlike Node.js and TypeScript, which supports unresolved paths, e.g. import thing from './file' and import thing from './', Deno only supports resolved paths, e.g. import thing from ./file.ts and import thing from https://unpkg.com/badges@^4.13.0/edition-deno/index.ts. This means that anything imported into Deno must be directly resolvable and must use ECMAScript Modules (ESM). This is because Deno has no conception of package.json.

Unlike Node.js and TypeScript, which supports package.json to specify dependency versions so you can just do import dep from 'dep', instead Deno has no conception of package.json, so all dependencies must be imported via their CDN URL with reference to their version number, e.g. import dep from https://unpkg.com/dep@^1.0.0/file.ts.

Deno and Node.js different on their APIs. Several Node.js builtins can be aliases to Deno's std/node builtins, however several things such as __filename, __dirname require a polyfill, and other things have no direct compatibility so require different entries.

And in the end, you need to hope your dependencies are also compatible with Deno.

The Solution

make-deno-edition is a CLI tool that takes your source edition (whichever directory contains your package's typescript source files) and instantly applies the following changes to create a compatible deno edition in a deno-edition directory:

bultin imports (e.g. fs) are mapped to their corresponding deno std/node polyfill
certain globals (e.g. __filename and __dirname) are mappedd to their corresponding deno userland polyfilll
internal imports (any relative path to another file inside your source edition) are mapped to their typescript file, e.g. import thing from './file' and import thing from './file.js' becomes import thing from './file.ts
remote imports (e.g. any URL) are assumed to be compatible, as node.js doesn't support them, so it is assumed they are already deno compatible
dependency imports (e.g. any package you install into node_modules) are checked to see if they have a deno field in their package.json denoting where to look for the deno compatible entry file, or if their main field in the package.json ends with .ts then it is assumed to be deno compatible
1. so the more dependencies that make-deno-edition is run on, then the more dependents that can become compatible with deno

make-deno-edition will also intelligently ignore compatibility for files that are not essential, such as your test and utility files, but fail if compatibility for an essential file, such as an entry file and its required modules fail

Finally, make-deno-edition will also update your package.json file with the details for the deno entry file, as well as the deno edition metadata, such that other packages and toolchains can make use of your deno compatibility.

Usage

Complete API Documentation.

Preparation

If you are using boundation to automatically generate deno compatibility for your npm package, then you can skip this step.

If you haven't already done so, add the following editions metadata to your package.json file:

  "editions": [
    {
      "description": "TypeScript source code with Import for modules",
      "directory": "source",
      "entry": "index.ts",
      "tags": [
        "typescript",
        "import"
      ],
      "engines": false
    }
  ]

Make sure that the directory is where the source files are located, in the above example, they are located in a source directory, as it is with this repository.

Make sure that the entry is where the entry file is located within the edition directory, in the above example, the entry is index.ts, as it is with this repository.

Executable

If you are using boundation to automatically generate deno compatibility for your npm package, then you can skip this step.

Install make-deno-edition to your development dependencies using:

npm install --save-dev make-deno-edition

Then add a compile npm script to your package.json containing:

make-deno-edition --attempt

Alternatively, you can run it directly on your project via:

npx make-deno-edition --attempt

The --attempt flag will not emit a failure exit code if the deno edition generation was not successful. If you require a deno edition to be published, remove the --attempt flag.

Publishing

If you are using boundation to automatically generate compatible editions (web browsers, deno, multiple node.js versions) for your npm package, then you can skip this step.

If you are using projectz to automatically generate your README.md content, then you can skip this step.

If a deno edition was successfully created, it will be located in the edition-deno directory with the metadata added to the editions array in your package.json and a deno entry field also added to your package.json.

Consumers of your package who use make-deno-edition on their own package, will now be able to use your package's deno edition to further their own deno compatibility.

You can also instruct consumers of your package to directly use your deno edition, by informing them of its presence in your README.md file. You can use projectz to automatically insert this information for them, or you can use the following template:

<a href="https://deno.land" title="Deno is a secure runtime for JavaScript and TypeScript, it is an alternative for Node.js"><h3>Deno</h3></a>

``` typescript
import pkg from 'https://unpkg.com/YOURPACKAGENAME@^VERSION/edition-deno/ENTRY.ts'
```

API

API usage of make-deno-edition is to come.

Install

npm

Install Globally

Install: npm install --global make-deno-edition
Executable: make-deno-edition

Install Locally

Install: npm install --save make-deno-edition
Executable: npx make-deno-edition
Import: import * as pkg from ('make-deno-edition')
Require: const pkg = require('make-deno-edition')

Editions

This package is published with the following editions:

make-deno-edition/source/index.ts is TypeScript source code with Import for modules
make-deno-edition aliases make-deno-edition/edition-esnext/index.js
make-deno-edition/edition-esnext/index.js is TypeScript compiled against ESNext for Node.js 14 with Require for modules
make-deno-edition/edition-node-esm/index.js is TypeScript compiled against ESNext for Node.js with Import for modules