🦕 Release on NPM and on deno.land/x with a single codebase🦕
Home - Documentation - Demo repo
IMPORTANT: Deno will soon support NPM modules.
For NPM module authors this means that you’ll just need to tell your users to import your module like:import express from "npm:express@5";
.
Knowing that why would you want to use Denoify?
- To publish your module on deno.land/x.
- To ensure your module is retro compatible with Deno versions that do not feature NPM support.
- If your module belong in the 10% of NPM modules that doesn’t work out of the box. Denoify can help you providing Deno implementation for specific file of your module (xxx.deno.ts).
- Denoify enables to produce a very predictable distribution of your module for Deno with the node builtins ports pinned to a specific version. If you don’t use Denoify and users import your module like
import abc from "npm:your-module@1.2.3
Deno will pull the last version of https://deno.land/std/node. An update there could theoretically end up breaking your module on Deno.
What it is
A build tool that takes as input a TypeScript codebase that was meant to target node and/or the web and spits out a modified version of the source files ready to be deployed as a Deno module.
NOTE: Denoify won’t run on Deno, it is a Node module.
NOTE: Denoify is capable of recursively resolving dependencies!
It works out of the box with dependencies that uses denoify and there are many option for dealing with dependencies that won’t transpile automatically. See specific documentation
This tool is mainly for NPM module maintainer, to enable them to bring first-class citizen Deno support to their modules and do so without introducing breaking changes.
Motivations
- Although it is quite easy to port a module to Deno no one wants to maintain two codebase.
- Wouldn’t it be great to have a tool able to bring Deno support to NPM modules?
Example of modules using Denoify
Some modules that have been made cross-runtime using Denoify:
- hono
- EVT
- Nano JSX
- eta
- graphql-helix
- tsafe
- @sniptt/guards
- ok-computer
- run-exclusive
- Yolk
- …and many more great modules
Limitations
Coming up next is a detailed guide on how to set up denoify with your project and how to publish on deno.land/x but before anything here are the current limitations you need to be aware of.
- If your module is vanilla JS it needs to be ported to TypeScript first. (1)
require()
is not supported.- You can’t
fs.readFile()
files that are part of the module ( files inside ares/
directory for example ). (2)
(1) Don’t be afraid, renaming your source with .ts
and dropping some any
here
and there will do the trick.
You will be able to pull it off even if you aren’t familiar with typescript. Ref
(2) In Deno the files that forms your module won’t be pre-fetched and
placed in node_module
like in node so you won’t be able to access files that are not
on the disk.
Step by step tutorial
Check out this repo to see in practice how to set up Denoify in your project.
Need a hand? Do not hesitate to open a discussion.
Publishing on deno.land/x
🗣 NOTE TO THE COMMUNITY: I am please to see an increasing number of project using Denoify! 🎉
That said, looking at your setup, I see that you are almost all tracking thedeno_dist
directory on your default branch…deno_dist
should be git ignored, it’s not source code!
Please, do not hesitate to reach out if you need a hand.
Once you’ll have successfully build your module for Deno you will want to publish it on deno.land/x
to do that in a clean way, without tracking the deno_dist/
on your main branch you’ll need to setup a
CI workflow.
To do that you can use the .github/workflow/ci.yaml
from tsafe, you can copy paste it, it’s portable.
The idea is that it creates a latest
branch on every release (when you bump the package.json version) where the deno_dist
is present.
When registering your module on deno.land/x you will need to specify the subdirectory:
Do not hesitate to open a discursion if you are having issues.
GitHub API rate limit exceeded
Deal with If you run Denoify a lot outside of GitHub Actions pipelines you will eventually get the following error:RequestError [HttpError]: API rate limit exceeded for 176.170.197.165. (But here's the good news: Authenticated requests get a higher rate limit. Check out the documentation for more details.)
.
To fix it, create a GitHub Personal Access Token and provide it as the environnement variable GITHUB_TOKEN
when you run the build tool.
Example:
echo 'export GITHUB_TOKEN=ghp_xn8jsxZrUChs9nmfZPDSmxLrTJPVJy3Sxc5J' > ~/.bash_profile
source ~/.bash_profile
npx denoify
What’s new
NEW IN v1
import express from "express";
automatically converted into:import express from "npm:express@5";
(See this update)
Most project will now transpile successfully out of the box.
NEW IN v0.10
- Mitigate the risk of comment being accidentally modified.
- Possibility to specify output directory in the package.json’s denoify field. See doc.
- Support module augmentation:
declare module ...
. Example - Possibility to explicitly tell where the
index.ts
is located in the source. Doc
NEW IN v0.9
tsconfig.json
can be absent if outputDir is specified. See @zxch3n’s PR- Enable to configure the name of the output dir. It no longer has to be
deno_dist
. See @zxch3n’s PR
NEW IN v0.7
NEW IN v0.7
- Support for workspaces where
node_modules
are located in a parent directory.
Thx @hayes See issue - Add basic support for child_process.spawn (#785)
NEW IN v0.6
- Built in support for graphQL.
See how graphql-helix got graphql working beforev0.6
using a custom replacer referenced in thepackage.json
.
You can do the same with other modules using skypack.dev or jspm - It is now possible to use
console.log()
in custom replacers to help debug. - Some support for
crypto
node builtin.
NEW IN v0.5 Breaking changes
- All Denoify parameters are now gathered under a uniq
"denoify"
field. - Possibility to specify which files should be copied to the
deno_dist
directory (Previously onlyREADME.md
was copied).
Valid config example
Introduction video
NOTE: New features have been introduced since this meeting was hold