A demo project published on NPM and Deno.land that serve as a tutorial on how to setup Denoify

my-dummy-npm-and-deno-module

NOTE: For a new module name favor ‘_’ over ‘-’ in the module name as it is a deno requirement not to use ‘_’

Play

git clone https://github.com/garronej/my_dummy_npm_and_deno_module
cd my_dummy_npm_and_deno_module
npm install
npm run build # Some warning are expected. They are part of the tutorial.

# Run the sample with node
node dist/test/test1.js

# Run the sample with Deno
deno run --allow-read --allow-env deno_dist/test/test1.ts

Step 1: Using .deno.ts where needed

If Denoify fails to transpile some files, or if the transpiled files fails at runtime this is how you should proceed, example:

This file fails to transpile. (in reality in resent version of Deno it does but let’s assume it doesn’t):

src/lib/hash.ts

import * as crypto from "crypto";

export function sha256(input: string): string {
    return crypto
        .createHash("sha256")
        .update(input)
        .digest("hex");
}

We can create this file that export the same API but with a Deno native implementation.

src/lib/hash.deno.ts

import { Sha256 } from "https://deno.land/std@0.65.0/hash/sha256.ts";

export function sha256(input: string): string {

    return new Sha256()
        .update(input)
        .hex();

}

The best approach is to start by a little refactor, extracting the specific bit that are problematic for Deno in separate files and write xxx.deno.ts counterpart only for theses files.

Step 1.5: Using // @denoify-ignore

If you want Denoify to simply ignore some file in the transpilation you can add // @denoify-ignore at the top of the file.
Example src/bin/customReplacer.ts is Denoify-ignored so there is no deno_dist/bin/customReplacer.ts.

Step 2: Dealing with your dependencies

You can skip this section if you are okay with relying on deno experimental support for NPM modules or if you have provided a xxx.deno.ts specific implementation everywhere you use dependencies.

"dependencies": {
    "ts-md5": "^1.2.7"
}
"denoify": {
    "ports": {
        "ts-md5": "garronej/ts-md5"
    }
}

"dependencies": {
    "js-yaml": "^3.13.1"
},
"denoify": {
    "ports": {
        "js-yaml": "https://deno.land/x/js_yaml_port/js-yaml.js"
    }
}

export function leftPad(str: string, maxLength: number){
    return str.padStart(maxLength);
}

"denoify": {
    "replacer": "dist/bin/customReplacer.js"
}

import * as ReactDOMServer from "react-dom";

// @deno-types="https://raw.githubusercontent.com/Soremwar/deno_types/master/react-dom/v16.13.1/server.d.ts"
import ReactDOMServer from "https://dev.jspm.io/react-dom@16.13.1/server.js";

Step 3: Edit tsconfig.json

Make sure you use the "outDir" compiler option.

Denoify reads the "outDir" field of the tsconfig.json filed to determine where to put the de generated source so it must be completed. The typical value to use is:

{
    "compilerOptions": {
        "outDir": "dist/"
    }
}

In this case the deno distribution will be placed in deno_dist/k.

Explicitly excludes the deno files from compilation

tsconfig.json

{
    "exclude": [
        "node_modules",
        "dist/",
        "deno_dist/",
        "src/**/*.deno.ts",
        "src/**/*.deno.tsx",
    ]
}

Enable strict mode and fixes errors if any.

By default Deno has all strict compiler options enabled so if you want your module to run on deno regardless of the context you must set:

{
    "compilerOptions": {
        "noUnusedLocals": true, 
        "noUnusedParameters": true, 
        "strict": true 
    }
}

It might rise a lot of error but they are all very easy to fix even if you are not familiar with the codebase.

function myFun(a): number{
    this.doSomething(a);
}

function myFun(this: any, a: any): number{
    this.doSomething(a);
}

x.doSomething();

x!.doSomething();

class Foo {
    n: number;
}

class Foo {
    n!: number;
}

describe(...)

declare const describe: any;
describe(...)

const x=3;

const x=3; x;

Step 4: Edit your npm scripts

First off, run $ npm install --save-dev denoify then add/edit the npm scripts:

package.json:

    "devDependencies": {
        "denoify": "^4.0.1",
    }
    "scripts": {
        "build": "tsc && denoify",
    }

(OPTIONAL) Step 4.5: Specify the output directory

If you don’t want your deno distribution to be generated in the deno_dist/ directory but rather in an other directory create a .denoifyrc.json configuration file and use the out option.

.denoifyrc.json:

{
    "out": "a/b/c/deno_lib"
}

(OPTIONAL) Step 4.75: Specify where the index.ts is located in your source.

In some project configuration denoify fails to locate where the index.ts is located.
You can specify it explicitly like so:

.denoifyrc.json:

{
    "index": "src/lib/index.ts"
}

Step 5: Chose what files you wish to include in the deno_dist directory.

By default, if present, the README.md and the LICENSE files are copied over the deno_dist directory. If you wish to includes other files you can use the denoify includes option: package.json

{
    "includes": [ ... ]
}

Have a look at the .denoifyrc.json of this repo for ans example.

Building

Now every time you will run $ npm run build the sources for deno will be updated in deno_dist/

It is also a good idea to add scripts to run tests on Node and on Deno. Note that in this repo we run the tests with the --allow-read because we use fs but if you module do not access files on the disk you don’t need it.

Create a new GitHub release every time you publish on npm.

Just after running $ npm publish got to your GitHub repo pages -> release -> create new release ( or draft new release ) and tag version enter v1.0.1 matching the current version in your package.json file.

(Optional) Publish your module on deno.land

Navigate to deno.land/x, click Add a module then follow the instruction. Use deno_dist/ as subdirectory when asked.

Accessing files on the disk

import * as fs from "fs";
import * as path from "path";
import { TextDecoder } from "util";

export function getDatabase(): Record<string,any> {
    return JSON.parse(
        new TextDecoder("utf-8").decode(
            fs.readFileSync(
                path.join(
                    __dirname,
                    "..", "database.json"
                )
            ) as Uint8Array
        )
    );
}

Conclusion

It is now possible to use your module on node using ( assuming you have published it with npm publish ):

$ npm install --save my-dummy-npm-and-deno-module then:

import { Cat } from "my-dummy-npm-and-deno-module"

And on deno with:

import { Cat } from "https://deno.land/x/my_dummy_npm_and_deno_module@v1.0.1/mod.ts";

or if you haven’t published on deno.land/x:

import { Cat } from "https://raw.githubusercontent.com/garronej/my_dummy_npm_and_deno_module/v1.0.1/deno_dist/mod.ts";

On top of that this module can now be used as a dependency in other modules that uses denoify.

If you want to avoid tracking the deno_dist/ directory and automates the publishing process checkout tsafe CI setup.