Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Condense Readme #41

Merged
merged 2 commits into from
Aug 7, 2023
Merged

Condense Readme #41

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
395e303
Condense Readme
wojpawlik Jul 26, 2023
5e2c3fa
Update testing section
wojpawlik Aug 7, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 20 additions & 47 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,9 @@

`tsc` replacement for transpiling [Deno] libraries to run on [Node.js].

> **Note** You don't need this if you maintain a npm package Deno can already
> run: https://deno.land/manual/node

![Because Deno's tooling is way simpler than
Node's](https://pbs.twimg.com/media/FBba11IXMAQB7pX?format=jpg)

Expand All @@ -14,31 +17,21 @@ Run `npx deno2node --init` in an empty directory.

## CLI Usage From Node.js

First, install `deno2node`.

```sh
npm install --save-dev deno2node
```

Then, create a [`tsconfig.json`], if you don't have one already.

It is useful to put `deno2node` in a prepare script. You can configure this by
running the following command.

```sh
npm install -ED deno2node
npm pkg set scripts.prepare=deno2node
```

You can now invoke `deno2node` by running
> **Note** New features or TypeScript upgrades may change output or diagnostics
> across minor versions of `deno2node`. Use `--save-prefix='~'` or
> `--save-exact` (`-E`) to avoid unexpected failures.

```sh
npm run prepare
```
Create a [`tsconfig.json`] to specify `"compilerOptions"` and `"files"` to
`"include"`, if you don't have one already.

It will alse be executed automatically when you run `npm install`.
You can now invoke `deno2node` by running `npm run prepare`.

> **Note** Deno can run many Node packages out of the box:
> https://deno.land/manual/node
It will alse be executed automatically when you run `npm install`.

## CLI Usage From Deno

Expand Down Expand Up @@ -68,16 +61,9 @@ enough for most needs.

### Shimming

Some things are global in Deno, but not in Node.js. One example for this is
`fetch`. Consequently, you need to _shim_ them, i.e. provide code that
supplements the missing globals.

> **Note** `deno2node` does not actually touch global definitions. Instead, it
> only injects import statements in the respective modules.

Install the packages providing the shims.
Some things are global in Deno, but not in Node.js.

Now, create a file that exports the globals you need:
To rectify this, create a file that exports shims for the globals you need:

```ts
// @filename: src/shim.node.ts
Expand All @@ -89,8 +75,8 @@ export { Deno } from "@deno/shim-deno";
export { alert, confirm, prompt } from "@deno/shim-prompts";
```

Lastly, you need to register your shims in `tsconfig.json` so `deno2node` can
inject them for you:
Then, register your shims in [`tsconfig.json`], so `deno2node` can import them
where needed:

```jsonc
// @filename: tsconfig.json
Expand Down Expand Up @@ -175,34 +161,21 @@ Confer the automatically generated [API Reference] if you want to use

## Testing

Build tests alongside source, and run them on Node.js with [`@fromdeno/test`].

## Contributing

`make watch` or `npm test -- --watch` to test on file change.

`make` or `npm it` to install dependencies, build, and test the project.
Register tests via `"node:test"`, and build them alongside the source.

`git config core.hooksPath scripts/hooks/` to `make` before each commit.
Then, test with `deno test src/` _and_ `node --test lib/`.

## Versioning
## Contributing

Similar to `tsc`, new features or TypeScript upgrades may alter output or
diagnostics of the CLI across minor versions. While this usually does not break
anything, you may still want to pin the minor version, hence only allowing patch
updates. You can do this by adding a `~` prefix to the version in your
`package.json` file.
`npm it` to install dependencies, build, and test the project.

```sh
npm install --save-dev --save-prefix='~' deno2node
```
`git config core.hooksPath scripts/hooks/` to build before each commit.

[deno]: https://deno.land/
[node.js]: https://nodejs.org/
[`dnt`]: https://github.com/denoland/dnt
[`grammy`]: https://github.com/grammyjs/grammY
[`pnpm`]: https://github.com/pnpm/pnpm#background
[`ts-morph`]: https://github.com/dsherret/ts-morph
[`@fromdeno/test`]: https://github.com/fromdeno/test
[`tsconfig.json`]: https://www.typescriptlang.org/docs/handbook/tsconfig-json.html
[api reference]: https://doc.deno.land/https/deno.land/x/deno2node/src/mod.ts