• Vals are the primitive of Val Town like Tweets are the primitive of Twitter.
  • Vals are snippets JavaScript or TypeScript that defines a single, named value.
  • Every change in a val is saved as a new version.
  • There are two kinds of vals: JSON vals and Function Vals.

The two kinds of Vals


A JSON Val is created when you evaluate some JavaScript or TypeScript. The result is saved as JSON and can be referenced in other Vals. JSON Vals are evaluated at a point in time. Their value is only recomputed when you re-evaluate them manually. JSON vals can also display logs and errors.

Function Vals

A function val is created when you save a JavaScript/TypeScript function. All calls to function vals are tracked and can be viewed by the caller of the function by clicking the ▶️ button in the bottom-right corner of a Val.

Run Your First Val

  1. Press Inspiration to cycle through a list of example expressions you can run.
  2. Press Run example to run that example.
  3. Feel free to edit any of the examples or run any JavaScript code you want.

Val Names

Vals are named like a variable let myName = .... If you don’t supply a name, one will be assigned.

You can only have a single-top level binding in a Val. If you have more than one statement in your code at the top-level, we will automatically wrap your code in an IIFE. For example, when you run this:


It becomes this:

You can then reference @me.untitled_RfqtWbJz in other Vals and it will refer to 3.

Publishing a Val

This was recently updated. View upgrade guide:
Simplified Val Privacy (May 15, 2023)

All Vals default to private. You can publish a Val by clicking the 🔒 next to its name. Anyone can see and run public Vals. Nobody will be able to inspect any of your private state (either a private Val or a secret) in a public Val. Publishing your Val makes it accessible via API, inside and outside of Val Town.

Referencing a Val

A val can reference other vals, much like a tweet can reference other tweets. For example, this val references the the prior example:

Once you type @ you will get helpful autocomplete on handles and then val names.

Referencing Private Vals

Anyone can reference any public val. Private vals can only be accessed by their authors. For example, I created a private val, example3. You won’t be able to see or reference example3 but I can! I can even export a val that uses example3, still without making example3 public as shown below.

Mutable State / Persistence

You can edit vals under your @username namespace inside other vals. Mutable state / persistence is just another kind of val.

At the end of a val’s execution any of state under the author’s namespace that has been edited will be saved as a new version of that val. For example, I have a public val @stevekrouse.exampleState:

I can mutate this state from another val:

If you call this @stevekrouse.exampleStatePlusPlus(), it will fail to mutate my state. You don’t have the permissions for that. However because I exported this function, you can call it via the API and that will mutate my state:


Vals are immutable but you can publish new versions of vals. Versions start at v0 and go up from there. When you reference a val, you always get the most recent version. You can toggle which version you’re looking at via the drop down menu next to the val’s name.

In the future, we will allow you to specifically reference a version, such as @stevekrouse.example3_v2.

Deleting a Val

You can delete a val you created via the 🗑️ button. You can either delete a specific version or all versions. You can restore any deleted val version at /settings/versions.

Linking to a Val

You can get a link to a val in the Share menu or via

Embedding a Val

You can get an embed link to a val in the Share menu or via You can paste that link into a tool like Notion and it’ll just work. For other context, you may need to use an iframe.

Included environment

Vals are evaluated on a limited subset of deno. It includes:

  • fetch to make HTTP requests
  • Buffer - to encode/decode strings
  • dynamic import from npm and https

Keyboard Shortcuts

  • ctrl/cmd-enter to run a val
  • ctrl/cmd-k to search for a val
  • ctrl/cmd-click to go to a val reference or URL


The limitations on vals can be found on our pricing page.