https://github.com/aaronhuggins/deno_run

A project manifest and runner for Deno.
https://github.com/aaronhuggins/deno_run

Last synced: 9 days ago
JSON representation

A project manifest and runner for Deno.

• Host: GitHub
• URL: https://github.com/aaronhuggins/deno_run
• Owner: aaronhuggins
• License: mit
• Created: 2020-09-09T14:12:20.000Z (about 4 years ago)
• Default Branch: master
• Last Pushed: 2020-09-14T13:17:44.000Z (about 4 years ago)
• Last Synced: 2024-05-01T19:30:59.079Z (7 months ago)
• Language: TypeScript
• Size: 51.8 KB
• Stars: 0
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE.md

Awesome Lists containing this project

README

        
# deno_run

A project manifest definition and runner for Deno.

## Usage

Install using `deno` to bootstrap [`deno_run`](https://deno.land/x/deno_run):

```shell

deno install --allow-run https://deno.land/x/deno_run/deno_run.ts bootstrap

```

If already installed, `deno_run` can upgrade itself:

```shell

deno_run upgrade https://deno.land/x/deno_run/

```

Then, projects which implement DenoManifest as `manifest.ts` can be run or installed using `deno_run`:

```shell

# Runs a project manifest.

deno_run https://deno.land/x/some_project/manifest.ts

# Installs

deno_run install https://deno.land/x/some_project/manifest.ts

# Upgrades

deno_run upgrade https://deno.land/x/some_project/manifest.ts

```

The user will be prompted to accept permissions from the manifest, with a clear, human-readable explanation of each requested permission.

For more details, run `deno_run help`.

## `manifest.ts`

The metadata for a Deno project which supports this tool can be found in a file named `manifest.ts` in the project root. It is a plain TypeScript file which exports either a default or a named `manifest` object. The export object **must** conform to both the `DenoManifest` interface and the `DenoManifestSchema` JSON schema; these can be found in [`types.ts`](./types.ts). The manifest will be imported in a sandbox environment which disallows any privileged API and which strips the export of any non-primitive, non-object, non-array value.

An easy check-list for `manifest.ts`:

  - No use of `import`

  - No use of `Deno`, `window`, etc.

  - Does not export functions, classes, etc.

That's it, although a `validate` command is also offered. Using TypeScript to describe the metadata should come naturally in the context of Deno, and it should allow more complex composing of metadata since its code will be executed on import.

The manifest will then be used to construct the arguments for the project's entry module, whether installing or running using `deno_run`.

## Why

Not all projects are intended as modules; some (including this very one) are command line tools. End users should not have to worry about excessively long or descriptive commands in order to run or install command line tools. However, it should be possible to present users with the required permissions for a particular tool or project, and it should be possible to reason about a project's metadata.

There are multiple issues which discuss an equivalent to `package.json` or a permissions file:

  - https://github.com/denoland/deno/issues/5489

  - https://github.com/denoland/deno/issues/3675

  - https://github.com/denoland/deno/issues/3179

Many of these discussions include a lot of talk about Node.js doing things a certain way, and well, people are just used to it. I completely disagree; Deno is trying to accomplish something very intentional in breaking away from that ecosystem. Security, composability, and ease of use are all a part of the forward-path for Deno, as well as more that's not yet well-defined or yet well-understood. The author of `deno_run` is opinionated that Deno is the proper place for package management and tooling; the manifest file is not for every Deno project but is instead meant to remove friction where it concerns running and installing Deno projects which are command line tools.