Newlyweds Proposing Marriage

    make-deno-edition
    TypeScript icon, indicating that this package has built-in type declarations

    1.3.0 • Public • Published

    make-deno-edition

    Status of the GitHub Workflow: bevry NPM version NPM downloads Dependency Status Dev Dependency Status
    GitHub Sponsors donate button Patreon donate button Flattr donate button Liberapay donate button Buy Me A Coffee donate button Open Collective donate button crypto donate button PayPal donate button Wishlist browse button

    Automatically makes package.json projects (such as npm packages and node.js modules) compatible with Deno.

    Overview

    Examples

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

    Interactive

    These are some highlighted packages that have interactive examples for the different targets they support, and whose compatibility for Deno was provided automatically by make-deno-editions, illustrating how easy multi-target production and consumption is of write-once packages.

    The Need

    Node.js and TypeScript support unresolved paths, e.g. import thing from './file' and import thing from './'. Deno however, 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).

    Node.js and TypeScript support package.json files to specify dependency versions, which enables code like import dep from 'dep'. Deno however, has no conception of package.json, so all dependencies must be imported via a directly resolvable CDN URL, e.g. import dep from 'https://unpkg.com/dep@^1.0.0/file.ts'.

    Deno and Node.js different on their APIs. Node.js builtins can be converted 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.

    In the end, you must 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 creates a compatible deno edition in a edition-deno directory.

    It provides this compatibility by providing the following transformations:

    1. bultin imports (e.g. fs) are mapped to their corresponding deno std/node polyfill

    2. certain globals (e.g. __filename and __dirname) are mapped to their corresponding deno userland polyfilll

    3. internal imports (any relativeu 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

    4. 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

    5. dependency imports (e.g. any package you install into node_modules) are supported if:

      1. If they have a deno field in their package.json, which will denote where to look for the deno compatible entry file

        The more dependencies that make-deno-edition is run on, then the more dependencies will automatically have a deno entry field, and thus the more dependencies will be automatically compatible with Deno, enabling more dependents to be automatically compatible with Deno.

      2. If they have a main field in the package.json that ends with .ts (is a typescript file), then it is assumed to be deno compatible

    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'
    ```
    

    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-es2020/index.js
    • make-deno-edition/edition-es2020/index.js is TypeScript compiled against ES2020 for Node.js 10 || 12 || 14 with Require for modules
    • make-deno-edition/edition-es2020-esm/index.js is TypeScript compiled against ES2020 for Node.js 12 || 14 with Import for modules

    History

    Discover the release history by heading on over to the HISTORY.md file.

    Contribute

    Discover how you can contribute by heading on over to the CONTRIBUTING.md file.

    Backers

    Maintainers

    These amazing people are maintaining this project:

    Sponsors

    No sponsors yet! Will you be the first?

    GitHub Sponsors donate button Patreon donate button Flattr donate button Liberapay donate button Buy Me A Coffee donate button Open Collective donate button crypto donate button PayPal donate button Wishlist browse button

    Contributors

    These amazing people have contributed code to this project:

    Discover how you can contribute by heading on over to the CONTRIBUTING.md file.

    License

    Unless stated otherwise all works are:

    and licensed under:

    Install

    npm i make-deno-edition

    DownloadsWeekly Downloads

    3,344

    Version

    1.3.0

    License

    MIT

    Unpacked Size

    98 kB

    Total Files

    23

    Last publish

    Collaborators

    • bevryme