Trex 🦕

Package management for deno (pronounced “tee rex”)

GitHub issues GitHub forks GitHub stars GitHub license

Use Trex

About

Trex is a package management tool for deno similar to npm but keeping close to the deno philosophy. Packages are cached and only one import_map.json file is generated.

// import_map.json

{
  "imports":  {
    "http/":  "https://deno.land/std/http/"
  }
}

For more information about the import maps in deno see import maps.

Additional topics

Installation

Install from the nest.land module registry (explicit version is required):

deno install -A --unstable -n trex https://x.nest.land/Trex@<version>/cli.ts

note: Works with deno >= 1.0.0.

Or from deno.land:

deno install -A --unstable -n trex https://deno.land/x/trex/cli.ts

we shorten the install command so it’s not that long

The permissions that Trex uses are:

  • –allow-net
  • –allow-read
  • –allow-write
  • –allow-run
  • –allow-env

You can give those permissions explicitly.

Updating Trex

Install new version with the -f flag:

deno install -f -A --unstable -n trex https://deno.land/x/trex/cli.ts

Or use the update command:

trex update

Note: available for versions 0.2.0 or higher.

Verify the installation of Trex:

trex --version

and the console should print the Trex version.

For help on the commands that Trex provides, use:

trex --help

For a better implementation of this tool you can use the Commands utility.

Usage

Installing from deno.land

Install the fs, http and fmt modules from std:

trex install --map fs http fmt

note: you can use trex i --map fs http fmt

--map installs packages from the standard library and those hosted at deno.land/x

Installing from nest.land

Install a package hosted on nest.land:

trex install --nest opine@0.13.0

note: if you want to install a package using nest.land you must specify a version explicitly as above

You can install packages from std hosted in nest.land by specifying the package and the version:

trex install --nest fs@0.61.0

Installing from a repository

trex install --pkg [user]/[repo or repo@tag]/[path/to/file] [packageName]

Example:

trex install --pkg oakserver/oak/mod.ts oak

The above downloads oak directly from its repository.

Example import map

All installation methods produce an import_map.json file:

{
  "imports": {
    "fs/": "https://deno.land/std/fs/",
    "http/": "https://deno.land/std/http/",
    "fmt/": "https://deno.land/std/fmt/"
  }
}

Downloading packages

Download all the packages listed in the import_map.json similar to npm install:

trex install

Adding custom packages

Install a package from a custom URL source:

trex --custom React=https://dev.jspm.io/react/index.js

import_map.json:

{
  "imports": {
    "http/": "https://deno.land/std/http/",
    "fmt/": "https://deno.land/std/fmt/",
    "oak": "https://deno.land/x/oak/mod.ts",
    "React": "https://dev.jspm.io/react/index.js"
  }
}

Deprecated! Installing global scripts (cmdline tools etc.)

Trex allows installing executable scripts from its database, for example:

List of installable tools

Use the getTool subcommand:

trex getTool Commands

note: If you are a linux/MacOs user you’ll have to specificate the PATH manually to use tools: export PATH="/home/username/.deno/bin:\$PATH"

Deleting packages

trex delete React

Remove a specific version from the cache and the import_map.json file:

trex delete fs@0.52.0

import_map.json:

{
  "imports": {
    "fs/": "https://deno.land/std/fs/",
    "http/": "https://deno.land/std/http/",
    "fmt/": "https://deno.land/std/fmt/",
    "oak": "https://deno.land/x/oak/mod.ts"
  }
}

Removing from cache only works with standard packages and those installed from deno.land/x

Selecting a specific version of a package

Specify a package’s version:

trex install --map fs@0.54.0

import_map.json

{
  "imports": {
    "fs/": "https://deno.land/std@0.54.0/fs/"
  }
}

note: can be used with third party packages.

Deprecated! Verifying dependency versions

trex --deps

For the following import map:

// in import_map.json
{
  "imports": {
    "oak": "https://deno.land/x/oak@v4.0.0/mod.ts",
    "http/": "https://deno.land/std@0.51.0/http/"
  }
}

The --deps flag prints out:

name module url version latest upToDate
oak oak “https://deno.land/x/oak@v4.0.0/mod.ts” “v4.0.0” “v5.0.0” false
http/ std “https://deno.land/std@0.54.0/http/” “0.54.0” “0.54.0” true

This functionality is based on the deno-check-updates tool by Fzwael.

Checking a package’s dependency tree

trex treeDeps fs

This prints out something like:

local: C:\Users\trex\AppData\Local\deno\deps\https\deno.land\434fe4a7be02d187573484b382f4c1fec5b023d27d1dcf4f768f300799a073e0
type: TypeScript
compiled: C:\Users\trex\AppData\Local\deno\gen\https\deno.land\std\fs\mod.ts.js
map: C:\Users\trex\AppData\Local\deno\gen\https\deno.land\std\fs\mod.ts.js.map
deps:
https://deno.land/std/fs/mod.ts
  ├─┬ https://deno.land/std/fs/empty_dir.ts
  │ └─┬ https://deno.land/std/path/mod.ts
  │   ├── https://deno.land/std/path/_constants.ts
  │   ├─┬ https://deno.land/std/path/win32.ts
  │   │ ├── https://deno.land/std/path/_constants.ts
  │   │ ├─┬ https://deno.land/std/path/_util.ts
  │   │ │ └── https://deno.land/std/path/_constants.ts
  │   │ └── https://deno.land/std/_util/assert.ts
  │   ├─┬ https://deno.land/std/path/posix.ts
  │   │ ├── https://deno.land/std/path/_constants.ts
  │   │ └── https://deno.land/std/path/_util.ts
  │   ├─┬ https://deno.land/std/path/common.ts
  │   │ └─┬ https://deno.land/std/path/separator.ts
  │   │   └── https://deno.land/std/path/_constants.ts
  │   ├── https://deno.land/std/path/separator.ts
  │   ├── https://deno.land/std/path/_interface.ts
  │   └─┬ https://deno.land/std/path/glob.ts
  │     ├── https://deno.land/std/path/separator.ts
  │     ├─┬ https://deno.land/std/path/_globrex.ts
  │     │ └── https://deno.land/std/path/_constants.ts
  │     ├── https://deno.land/std/path/mod.ts
  │     └── https://deno.land/std/_util/assert.ts
  ├─┬ https://deno.land/std/fs/ensure_dir.ts
  │ └─┬ https://deno.land/std/fs/_util.ts
  │   └── https://deno.land/std/path/mod.ts
  ├─┬ https://deno.land/std/fs/ensure_file.ts
  │ ├── https://deno.land/std/path/mod.ts
  │ ├── https://deno.land/std/fs/ensure_dir.ts
  │ └── https://deno.land/std/fs/_util.ts
  ├─┬ https://deno.land/std/fs/ensure_link.ts
  │ ├── https://deno.land/std/path/mod.ts
  │ ├── https://deno.land/std/fs/ensure_dir.ts
  │ ├── https://deno.land/std/fs/exists.ts
  │ └── https://deno.land/std/fs/_util.ts
  ├─┬ https://deno.land/std/fs/ensure_symlink.ts
  │ ├── https://deno.land/std/path/mod.ts
  │ ├── https://deno.land/std/fs/ensure_dir.ts
  │ ├── https://deno.land/std/fs/exists.ts
  │ └── https://deno.land/std/fs/_util.ts
  ├── https://deno.land/std/fs/exists.ts
  ├─┬ https://deno.land/std/fs/expand_glob.ts
  │ ├── https://deno.land/std/path/mod.ts
  │ ├─┬ https://deno.land/std/fs/walk.ts
  │ │ ├── https://deno.land/std/_util/assert.ts
  │ │ └── https://deno.land/std/path/mod.ts
  │ └── https://deno.land/std/_util/assert.ts
  ├─┬ https://deno.land/std/fs/move.ts
  │ ├── https://deno.land/std/fs/exists.ts
  │ └── https://deno.land/std/fs/_util.ts
  ├─┬ https://deno.land/std/fs/copy.ts
  │ ├── https://deno.land/std/path/mod.ts
  │ ├── https://deno.land/std/fs/ensure_dir.ts
  │ ├── https://deno.land/std/fs/_util.ts
  │ └── https://deno.land/std/_util/assert.ts
  ├── https://deno.land/std/fs/read_file_str.ts
  ├── https://deno.land/std/fs/write_file_str.ts
  ├── https://deno.land/std/fs/read_json.ts
  ├── https://deno.land/std/fs/write_json.ts
  ├── https://deno.land/std/fs/walk.ts
  └── https://deno.land/std/fs/eol.ts

Integrity checking & lock files

Let’s say your module depends on a remote module. When you compile your module for the first time, it is retrieved, compiled and cached. It will remain this way until you run your module on a new machine (e.g. in production) or reload the cache.

But what happens if the content in the remote url is changed? This could lead to your production module running with different dependency code than your local module. Deno’s solution to avoid this is to use integrity checking and lock files.

Create a lockfile:

trex --lock file.ts

The above generates a lock.json file.

If you use import_map.json in input file, you can specify it:

trex --lock --importmap file.ts

See deno document for more info.

Complete example

A simple std server

Install http and fmt:

trex install --map http fmt

Create a simple server:

// server.ts
import { serve } from "http/server.ts";
import { green } from "fmt/colors.ts";

const server = serve({ port: 8000 });
console.log(green("http://localhost:8000/"));

for await (const req of server) {
  req.respond({ body: "Hello World\n" });
}

Run the server:

deno run --allow-net --importmap=import_map.json --unstable server.ts

note: it is important to use –importmap=import_map.json –unstable

Adding third party packages

Example using oak

Add the master version of oak:

trex i --map oak

This adds oak to the import_map.json file:

{
  "imports": {
    "http/": "https://deno.land/std/http/",
    "fmt/": "https://deno.land/std/fmt/",
    "oak": "https://deno.land/x/oak/mod.ts"
  }
}

note: third party packages are added using mod.ts

Then create an oak application. Note the import statement.

// app.ts
import { Application } from "oak";

const app = new Application();

app.use((ctx) => {
  ctx.response.body = "Hello World!";
});

await app.listen({ port: 8000 });

Run the server:

deno run --allow-net --importmap=import_map.json --unstable app.ts

Contributing

Contributions are welcome, see CONTRIBUTING GUIDELINES.

Licensing

Trex is licensed under the MIT license.


Trex is powered by