Edit on val.town ↗

Importing

One of the best features of Val Town is the ability to import modules. There are thousands of modules written in JavaScript and TypeScript that you can instantly import to extend and supercharge your vals.

Val Town supports importing code from a variety of sources, including other vals on Val Town, NPM, JSR, esm.sh, deno.land. You can also import code from arbitrary URLs if they provide the correct Content-Type header and contain JavaScript or TypeScript. Imports in Val Town work the same as in Deno, so you can learn more from their docs.

To import an npm module, like zod, add npm: in front of the name. So,

import { z } from "npm:zod";

NPM compatibility and the sandbox: Most NPM modules are supported and will work great in Val Town. However, we do run in a security sandbox: a val can't access the filesystem. Some NPM modules try to do that, and won't be able to. Using esm.sh is often an effective workaround for these modules. See permissions errors for more information.

Val Town supports importing JSR modules. Simply add jsr: and @ in front of the module name:

import { concat } from "jsr:@std/bytes";

To import from a URL, like from esm.sh, you just specify the full url. For example, to import zod from esm.sh:

import { z } from "https://esm.sh/zod";

If you want to import a Node.js built-in module, add node: in front of its name. For example, to import the crypto module, use this, which is the same as what Node.js themselves officially recommend:

import { createHmac } from "node:crypto";

Within vals, you can import files and folders relative to the val root (e.g., ./home), which means you don't have to update your imports when you branch, remix, or rename a val.

Between different vals, you can still import code freely. In the ⋮ menu in the top-right of the val code editor, go to Copy → Copy module URL to copy the module URL. Then you can import from that URL from another val.

Val source code hosted on esm.town, and are available for import on Val Town, Deno, Node, the browser, and anywhere else https-imports are supported. In this way, Val Town builds upon the new http-style imports, to make a lightweight package registry, but where each snippet of code is a package.

Private vals are only importable with the DENO_AUTH_TOKEN environment variable set, which we automatically set for you, allowing only you to import your private vals.

As of Deno 2.8, Val Town supports importing text files like HTML, CSS, JSON, Markdown, CSV, TXT, etc.

import text from "./logs.txt" with { type: "text" };
import html from "./index.html" with { type: "text" };
import styles from "./styles.css" with { type: "text" };
import markdown from "./blog.md" with { type: "text" };

You can also dynamically import text files inline:

const data = (await import("./data.csv", {
  with: { type: "text" },
})).default;

And you can import json in Deno as text or JSON, which will parse it into a JavaScript object:

import config from "./data.json" with { type: "json" };

Whenever you go to use a new npm library, we recommend first searching to see if anyone has used that library before. You can find the most common packages here.

Or you could look for examples related to cheerio by searching for it or even more pointedly by searching for "npm:cheerio".

It's often not clear how a library will expose its methods. It can be helpful to log the keys of whatever object they return to you. That will tell you if you need to import it off of default or not, and what is available to you.

import * as cheerio from "npm:cheerio";

console.log(Object.keys(cheerio));
[
  'contains', 'default',
  'html',     'load',
  'merge',    'parseHTML',
  'root',     'text',
  'xml'
]

Not all modules are compatible with Deno. Some modules are written with only Node.js or a browser environment in mind, and won't work with Deno. While Deno implements most of the functionality of Node.js and some of the functionality of browsers - so many modules will "just work" in it, some won't.

Also, some modules are written with the assumption that they can access system resources, compile C code, and more, so they won't work in a secure environment like Val Town.

We're here to help As always, ask in our Discord if you want help.

Last updated