Val Town

https://docs.val.town
Admin
Val Town is a collaborative platform to write, deploy, and scale serverless JavaScript for creating...
Tokens:40,870
Snippets:591
Trust Score:10
Update:6 months ago
Show doc for...
Tokens:
Raw
### Setting up an example Node.js project

Source: https://docs.val.town/reference/api/sdk.md

Commands to initialize a new Node.js project and install the Val Town SDK dependency.

```bash
# Create a directory for your project
mkdir example-project
cd example-project
# Create a package.json file
npm init
# Install the SDK
npm install @valtown/sdk
```

--------------------------------

### Install Val Town CLI

Source: https://docs.val.town/guides/prompting/claude-code.md

Install the vt CLI tool via Deno to manage vals locally.

```bash
deno install -grAf jsr:@valtown/vt
```

--------------------------------

### JavaScript Request Example

Source: https://docs.val.town/openapi

Example of how to make a GET request to the Val Town API using JavaScript. This snippet demonstrates fetching an alias.

```JavaScript
fetch("https://api.val.town/v1/alias/{username}", {
  "method": "GET"
})
.then(response => {
  console.log(response);
})
.catch(err => {
  console.error(err);
});
```

--------------------------------

### Database connection response format

Source: https://docs.val.town/guides/databases/prisma-postgres.md

Example of the JSON output returned after creating a database.

```json
{
  "connectionString": "postgresql://...@db.prisma.io:5432/postgres?sslmode=require",
  "claimUrl": "https://create-db.prisma.io/claim?projectID=...",
  "deletionDate": "2025-11-27T11:03:38.153Z",
  "region": "ap-southeast-1",
  "name": "2025-11-26T11:03:34.105Z",
  "projectId": "proj_..."
}
```

--------------------------------

### Read lockfile contents

Source: https://docs.val.town/troubleshooting/permission-errors.md

Example of reading the deno.lock file, which is permitted within the sandbox.

```ts
console.log(Deno.readTextFileSync("deno.lock"));
```

--------------------------------

### Create a new Val

Source: https://docs.val.town/guides/prompting/cli.md

Use the `vt create` command to start a new Val project locally. This command will prompt to add editor files.

```bash
vt create
```

--------------------------------

### index.mjs

Source: https://docs.val.town/reference/api/sdk.md

Example implementation using ESM syntax to retrieve user profile information.

```ts
import ValTown from "@valtown/sdk";

const valTown = new ValTown();

async function main() {
  const myProfile = await valTown.me.profile.retrieve();
  console.log(myProfile);
}

main();
```

--------------------------------

### Val Town SDK File Operations

Source: https://docs.val.town/reference/file-io.md

These examples demonstrate how to perform file operations (read, create, update, list) using the Val Town SDK.

```APIDOC
## POST /vals/:valId/files/content

### Description
Reads the content of a file within a specified Val.

### Method
POST

### Endpoint
`/vals/:valId/files/content`

### Parameters
#### Path Parameters
- **valId** (string) - Required - The ID of the Val.

#### Request Body
- **path** (string) - Required - The path to the file within the Val.

### Request Example
```json
{
  "path": "path/to/file.txt"
}
```

### Response
#### Success Response (200)
- **content** (string) - The content of the file.

#### Response Example
```json
"File content here"
```

## POST /vals/:valId/files

### Description
Creates a file or directory within a specified Val.

### Method
POST

### Endpoint
`/vals/:valId/files`

### Parameters
#### Path Parameters
- **valId** (string) - Required - The ID of the Val.

#### Request Body
- **path** (string) - Required - The path for the new file or directory.
- **type** (string) - Optional - The type of the entry, either "file" or "directory". Defaults to "file".

### Request Example
```json
{
  "path": "new_directory",
  "type": "directory"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "File created successfully"
}
```

## PUT /vals/:valId/files

### Description
Updates the content of an existing file within a specified Val.

### Method
PUT

### Endpoint
`/vals/:valId/files`

### Parameters
#### Path Parameters
- **valId** (string) - Required - The ID of the Val.

#### Request Body
- **path** (string) - Required - The path to the file to update.
- **content** (string) - Required - The new content for the file.

### Request Example
```json
{
  "path": "path/to/file.txt",
  "content": "New file content"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "File updated successfully"
}
```

## GET /vals/:valId/files

### Description
Lists files and directories within a specified Val, optionally recursively.

### Method
GET

### Endpoint
`/vals/:valId/files`

### Parameters
#### Path Parameters
- **valId** (string) - Required - The ID of the Val.

#### Query Parameters
- **path** (string) - Optional - The directory path to list files from. Defaults to the root.
- **recursive** (boolean) - Optional - Whether to list files recursively. Defaults to false.

### Response
#### Success Response (200)
- **files** (array) - An array of file objects, each with a `path` and `type`.

#### Response Example
```json
[
  { "path": "file.txt", "type": "file" },
  { "path": "subdir", "type": "directory" }
]
```
```

--------------------------------

### Val Town Utility Functions

Source: https://docs.val.town/reference/file-io.md

These examples demonstrate how to use the built-in utility functions for file operations within Val Town.

```APIDOC
## Function: readFile

### Description
Reads the contents of a file from the current val or a specified val.

### Signature
```ts
readFile(path: string, metaImportUrl?: string): Promise<string>
```

### Parameters
- **path** (string) - Required - The file path to read (with or without leading slash).
- **metaImportUrl** (string) - Optional - The `import.meta.url` to determine which val to read from. Defaults to `Deno.env.get("VALTOWN_ENTRYPOINT")`.

### Example
```ts
import { readFile } from "https://esm.town/v/std/utils/index.ts";

// Read from current val
const content = await readFile("/README.md");
console.log(content);

// Read from a specific val
const content2 = await readFile("/README.md", import.meta.url);
console.log(content2);
```

## Function: listFiles

### Description
Lists all files in the current val or a specified val with their metadata.

### Signature
```ts
listFiles(metaImportUrl?: string): Promise<File[]>
```

### Parameters
- **metaImportUrl** (string) - Optional - The `import.meta.url` to determine which val to list files from. Defaults to `Deno.env.get("VALTOWN_ENTRYPOINT")`.

### Example
```ts
import { listFiles } from "https://esm.town/v/std/utils/index.ts";

// List files from current val
const files = await listFiles();
files.forEach((file) => console.log(file.path));

// List files from a specific val
const files2 = await listFiles(import.meta.url);
files2.forEach((file) => console.log(file.path));
```

## Function: listFilesByPath

### Description
Lists files in a specific directory path within the current val or a specified val.

### Signature
```ts
listFilesByPath(path: string, metaImportUrl?: string): Promise<File[]>
```

### Parameters
- **path** (string) - Required - The directory path to list files from.
- **metaImportUrl** (string) - Optional - The `import.meta.url` to determine which val to list files from. Defaults to `Deno.env.get("VALTOWN_ENTRYPOINT")`.

### Example
```ts
import { listFilesByPath } from "https://esm.town/v/std/utils/index.ts";

// List files in a specific directory
const frontendFiles = await listFilesByPath("frontend/");
frontendFiles.forEach((file) => console.log(file.path));
```

## Function: httpEndpoint

### Description
Gets the HTTP endpoint URL for a specific file in the val.

### Signature
```ts
httpEndpoint(path: string, metaImportUrl?: string): Promise<string>
```

### Parameters
- **path** (string) - Required - The file path to get the endpoint for.
- **metaImportUrl** (string) - Optional - The `import.meta.url` to determine which val the file belongs to. Defaults to `Deno.env.get("VALTOWN_ENTRYPOINT")`.

### Example
```ts
import { httpEndpoint } from "https://esm.town/v/std/utils/index.ts";

// Get the HTTP endpoint for a specific file
const endpoint = await httpEndpoint("/api/users.ts");
console.log(endpoint); // Returns the full HTTP URL for the endpoint
```
```

--------------------------------

### LSP JSON-RPC Message Example

Source: https://docs.val.town/reference/deno-lsp.md

Example of a JSON-RPC payload used to communicate with the Deno language server via the LSP protocol.

```json
{"jsonrpc":"2.0","method":"textDocument/didOpen","params":{"textDocument":{"uri":"file:///path/to/file.ts","languageId":"typescript","version":1,"text":"console.log('hello world!')"}}}
```

--------------------------------

### Running index.mjs and getting profile information

Source: https://docs.val.town/reference/api/sdk.md

Executes the script and displays the expected JSON output from the profile retrieval.

```bash
node index.mjs

{
  id: '19892fed-baf3-41fb-a5cc-96c80e95edec',
  bio: '👷 Building Val Town',
  username: 'tmcw',
  profileImageUrl: 'https://img.clerk.com/eyJ0eXBl…',
  tier: 'pro',
  email: 'tom@macwright.com'
}
```

--------------------------------

### Initialize and Select Data from Airtable

Source: https://docs.val.town/guides/airtable.md

This example demonstrates how to initialize the Airtable client with your API key, base ID, and table name, then select data from the table. Ensure your environment variable for the API key and your base ID/table name are correctly configured.

```typescript
import { Airtable } from "https://deno.land/x/airtable@v1.1.1/mod.ts";

const airtable = new Airtable({
  apiKey: Deno.env.get("airtable_pat"),
  baseId: "appXSrKDlwbAijRmD",
  tableName: "All content",
});
// Sample data from: https://blog.airtable.com/database-vs-spreadsheet/
const results = await airtable.select();
console.log(results);
```

--------------------------------

### Cron Expression Example

Source: https://docs.val.town/vals/cron.md

A cron expression representing a schedule that runs every two hours on the first day of the month.

```text
0 */2 1 * *
```

--------------------------------

### Hono Cache Middleware

Source: https://docs.val.town/vals/http/cdns.md

Configure Hono's cache middleware to cache responses for a specified duration. This example caches for 5 minutes.

```typescript
import { cache } from "hono/cache";
import { Hono } from "hono";
const app = new Hono();

app.get(
  "*",
  cache({
    cacheName: "my-app",
    cacheControl: "public, max-age=300", // cache for 5 minutes
    wait: true,
  })
);

app.get("/", (c) => {
  return c.html("Hello, world!");
});
```

--------------------------------

### Parse HTML with Cheerio

Source: https://docs.val.town/guides/web-scraping.md

Fetches HTML from a URL and parses it using Cheerio to extract specific text content based on a CSS selector. Ensure Cheerio is installed via npm.

```typescript
import { fetchText } from "https://esm.town/v/stevekrouse/fetchText?v=6";
import { load } from "npm:cheerio";

const html = await fetchText("https://en.wikipedia.org/wiki/OpenAI");
const $ = load(html);
// Cheerio accepts a CSS selector, here we pick the second <p>
const intro = $("p:nth-of-type(2)").first().text();
console.log(intro);
```

--------------------------------

### Insert Data into PlanetScale Table

Source: https://docs.val.town/guides/databases/planetscale

Insert one or more items into a PlanetScale table. This example uses parameterized queries to safely insert data. Requires environment variables to be configured.

```typescript
import { queryPlanetScale } from "https://esm.town/v/vtdocs/queryPlanetScale";

await queryPlanetScale(
  {
    host: Deno.env.get("planetScaleHost"),
    username: Deno.env.get("planetScaleUsername"),
    password: Deno.env.get("planetScalePassword"),
  },
  `INSERT INTO stock (name, price) VALUES (?, ?);`,
  ["banana", 15]
);
```

--------------------------------

### Get Github User with Octokit

Source: https://docs.val.town/guides/github/get-a-github-user.md

This Val demonstrates fetching a GitHub user using the `npm:@octokit/core` package. Ensure the GitHub API version is specified in the headers.

```typescript
import { Octokit } from "npm:@octokit/core";

export const getGithubUserViaOctokit = async (username: string) => {
  const octokit = new Octokit();
  const user = await octokit.request("GET /users/{username}", {
    username,
    headers: {
      "X-GitHub-Api-Version": "2022-11-28",
    },
  });
  return user;
};
```

--------------------------------

### Provision a database via CLI

Source: https://docs.val.town/guides/databases/prisma-postgres.md

Use the Prisma CLI to generate a new serverless database instance.

```bash
npx create-db --json
```

--------------------------------

### Get HTTP endpoint using utils

Source: https://docs.val.town/reference/file-io.md

Gets the HTTP endpoint URL for a specific file in the val.

```ts
import { httpEndpoint } from "https://esm.town/v/std/utils/index.ts";

// Get the HTTP endpoint for a specific file
const endpoint = await httpEndpoint("/api/users.ts");
console.log(endpoint); // Returns the full HTTP URL for the endpoint
```

--------------------------------

### Basic usage

Source: https://docs.val.town/reference/std/sqlite/usage.md

Demonstrates table creation, parameterized insertion, and data retrieval.

```ts
import { sqlite } from "https://esm.town/v/std/sqlite/main.ts";

await sqlite.execute(`create table if not exists kv(
  key text unique,
  value text
)`);

const key = crypto.randomUUID();
await sqlite.execute({ sql: `insert into kv(key, value) values(?, ?)`, args: [key, "value1"] });
const result = await sqlite.execute({ sql: `select * from kv where key = ?`, args: [key] });

console.log(result);
// {
//   columns: [ "key", "value" ],
//   columnTypes: [ "TEXT", "TEXT" ],
//   rows: [ { key: "d65991f8-6f03-4275-bcf1-1fdb1164e153", value: "value1" } ],
//   rowsAffected: 0,
//   lastInsertRowid: null
// }

const rows: { key: string; value: string }[] = result.rows as any;

console.log(rows); // [ { key: "d65991f8-6f03-4275-bcf1-1fdb1164e153", value: "value1" } ]
```

--------------------------------

### Initialize and Sync Vals with Windsurf

Source: https://docs.val.town/guides/prompting/windsurf.md

Commands to prepare a val directory and enable automatic synchronization with Val Town.

```bash
vt create
vt remix
vt clone
```

```bash
cd <val-directory>
```

```bash
vt checkout -b <branch>
```

```bash
vt watch
```

--------------------------------

### Create a Static HTTP Server with Hono

Source: https://docs.val.town/reference/file-io.md

Use this to serve static files from your val. It automatically handles index.html for root requests and content types for other files. It returns a fetch-compatible handler function.

```typescript
import { staticHTTPServer } from "https://esm.town/v/std/utils/index.ts";

// Most common usage - serves files from current val
export default staticHTTPServer();

// Explicit val specification
export default staticHTTPServer(import.meta.url);
```

--------------------------------

### Get JSON from Blob Storage

Source: https://docs.val.town/reference/std/blob.md

Retrieves a JSON object by its key. Returns undefined if the key does not exist.

```ts
import { blob } from "https://esm.town/v/std/blob";

let blobDemo = await blob.getJSON("myKey");
console.log(blobDemo); // returns `undefined` if not found
```

--------------------------------

### Lower-level Get Blob

Source: https://docs.val.town/reference/std/blob.md

Retrieves the raw content of a blob for a given key. Useful for non-JSON or binary data.

```APIDOC
## Lower-level Get Blob

### Description
Retrieves the raw content of a blob for a given key. Useful for non-JSON or binary data.

### Method
`GET` (implicitly via `blob.get`)

### Endpoint
`/v1/blob/{key}` (conceptual, accessed via SDK)

### Parameters
#### Path Parameters
- **key** (string) - Required - The unique identifier for the blob.

### Request Example
```typescript
import { blob } from "https://esm.town/v/std/blob";

// Assuming 'myBinaryKey' stores binary data
let blobData = await blob.get("myBinaryKey");
// Process blobData (e.g., as ArrayBuffer, Blob, ReadableStream)
```

### Response
#### Success Response (200)
- **value** (string | BodyInit) - The raw content of the blob. Can be a string or a `BodyInit` type for binary data.

#### Response Example
```
// Example for binary data (e.g., an image file content)
```
```

--------------------------------

### Using the SDK in Val Town

Source: https://docs.val.town/reference/api/sdk.md

Initializes the SDK within the Val Town environment where authentication is handled automatically via environment variables.

```ts
import ValTown from "npm:@valtown/sdk";

const vt = new ValTown();

// print your email
const me = await vt.me.profile.retrieve();
console.log(me.email);

// list some of your vals
const vals = await vt.me.vals.list({});
console.log(vals);
```

--------------------------------

### Get JSON Blob

Source: https://docs.val.town/reference/std/blob.md

Retrieves a JSON object stored under a specific key. Returns `undefined` if the key is not found.

```APIDOC
## Get JSON Blob

### Description
Retrieves a JSON object stored under a specific key. Returns `undefined` if the key is not found.

### Method
`GET` (implicitly via `blob.getJSON`)

### Endpoint
`/v1/blob/{key}` (conceptual, accessed via SDK)

### Parameters
#### Path Parameters
- **key** (string) - Required - The unique identifier for the blob.

### Request Example
```typescript
import { blob } from "https://esm.town/v/std/blob";

let blobDemo = await blob.getJSON("myKey");
console.log(blobDemo);
```

### Response
#### Success Response (200)
- **(JSON object or undefined)** - The JSON data associated with the key, or undefined if not found.

#### Response Example
```json
{
  "hello": "world"
}
```
```

--------------------------------

### staticHTTPServer

Source: https://docs.val.town/reference/file-io.md

Creates a Hono-based HTTP server that serves static files from your val, automatically handling index.html and file paths.

```APIDOC
## staticHTTPServer

### Description
Creates a Hono-based HTTP server that serves static files from your val. The server automatically serves /index.html for root requests and handles all other file paths.

### Parameters
- **importMetaURL** (string) - Optional - The import.meta.url to determine which val to serve files from. Defaults to Deno.env.get("VALTOWN_ENTRYPOINT").

### Usage Example
```ts
import { staticHTTPServer } from "https://esm.town/v/std/utils/index.ts";

// Most common usage - serves files from current val
export default staticHTTPServer();

// Explicit val specification
export default staticHTTPServer(import.meta.url);
```
```

--------------------------------

### Create a database table

Source: https://docs.val.town/guides/databases/prisma-postgres.md

Initialize a new table using the postgres client.

```typescript
import { Client } from "jsr:@db/postgres";

const client = new Client(Deno.env.get("PRISMA_POSTGRES_URL"));
await client.connect();

await client.queryObject`
  CREATE TABLE IF NOT EXISTS users (
    id SERIAL PRIMARY KEY,
    name TEXT NOT NULL,
    email TEXT NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
  )
`;

console.log("Table created!");
await client.end();
```

--------------------------------

### Permission error response

Source: https://docs.val.town/troubleshooting/permission-errors.md

Example of the JSON error returned when a module attempts to access restricted system paths.

```json
{
  "error": "Requires read access to <exec_path>, run again with the --allow-read flag"
}
```

--------------------------------

### Create a file using the SDK

Source: https://docs.val.town/reference/file-io.md

Creates a new file or directory entry within a val.

```ts
import ValTown from "npm:@valtown/sdk";
const vt = new ValTown();
const val_id = "your-val-id-here";
const file = await vt.vals.files.create(val_id, {
  path: "path",
  type: "directory",
});
```

--------------------------------

### Usage of getGithubUser Val

Source: https://docs.val.town/guides/github/get-a-github-user.md

Example of how to call the `getGithubUser` Val to retrieve and log a GitHub user's information.

```typescript
import { getGithubUser } from "https://esm.town/v/vtdocs/getGithubUser";

console.log(await getGithubUser("stevekrouse"));
```

--------------------------------

### Get Val Alias

Source: https://docs.val.town/openapi

Use this endpoint to retrieve an alias for a specific Val. Ensure the 'username' parameter is correctly provided.

```Shell
curl -X GET "https://api.val.town/v1/alias/{username}"
```

--------------------------------

### Get Alias Information

Source: https://docs.val.town/openapi

Retrieves information about a user's alias. This endpoint is useful for resolving user-specific Val Town identifiers.

```APIDOC
## GET /v1/alias/{username}

### Description
Retrieves information about a user's alias.

### Method
GET

### Endpoint
/v1/alias/{username}

### Parameters
#### Path Parameters
- **username** (string) - Required - The username for which to retrieve alias information.

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **field1** (type) - Description

#### Response Example
```json
{
  "example": "response body"
}
```
```

--------------------------------

### Clone an existing Val

Source: https://docs.val.town/guides/prompting/cli.md

Use the `vt clone` command to download an existing Val project to your local machine. This command will prompt to add editor files.

```bash
vt clone
```

--------------------------------

### Create, Remix, or Clone a Val with Editor Files

Source: https://docs.val.town/guides/prompting/warp.md

Initiate a new Val Town val or copy an existing one using `vt create`, `vt remix`, or `vt clone`. Select 'Yes' when prompted to add editor files, which includes configurations recognized by Warp.

```bash
vt create
```

```bash
vt remix
```

```bash
vt clone
```

--------------------------------

### Exporting a Handler Function

Source: https://docs.val.town/troubleshooting/exports.md

Use the 'export' keyword to define the function that will be executed when the val is triggered. This example shows a function named `handleEmail`.

```typescript
/**
 * Note the 'export' keyword
 */
export function handleEmail(email: Email) {
  console.log("ok!");
}
```

--------------------------------

### List files using utils

Source: https://docs.val.town/reference/file-io.md

Lists all files in the current val with their metadata.

```ts
import { listFiles } from "https://esm.town/v/std/utils/index.ts";

// Most common usage - lists files from current val
const files = await listFiles();
files.forEach((file) => console.log(file.path));

// Explicit val specification
const files2 = await listFiles(import.meta.url);
files2.forEach((file) => console.log(file.path));
```

--------------------------------

### Import NPM Module

Source: https://docs.val.town/reference/import.md

Prefix the module name with 'npm:' to import from NPM. Ensure the module is compatible with the Val Town sandbox, as filesystem access is restricted.

```typescript
import { z } from "npm:zod";
```

--------------------------------

### Get Github User with fetchJSON

Source: https://docs.val.town/guides/github/get-a-github-user.md

Use this Val to fetch a GitHub user object by username. It utilizes the `fetchJSON` function for making the API request.

```typescript
import { fetchJSON } from "https://esm.town/v/stevekrouse/fetchJSON?v=41";

export const getGithubUser = async (username: string) => {
  const user = await fetchJSON(
    `https://api.github.com/users/${username}`,
  );
  return user;
};
```

--------------------------------

### Get GitHub User Stars (TypeScript)

Source: https://docs.val.town/guides/github/github-users-stars-pagination.md

Fetches the total star count for a given GitHub username by paginating through their repositories. Requires the `fetchJSON` utility.

```typescript
import { fetchJSON } from "https://esm.town/v/stevekrouse/fetchJSON?v=41";

export const getGithubStars = async (username: string) => {
  const user = await fetchJSON(
    `https://api.github.com/users/${username}`,
  );
  let totalStars = 0;
  // Paginate the max number of pages per request
  let pages = Math.ceil(user.public_repos / 100);
  while (pages--) {
    for (
      const repo of await fetchJSON(
        `https://api.github.com/users/${username}/repos?per_page=100&page=${
          pages + 1
        }`,
      )
    ) {
      totalStars += repo.stargazers_count;
    }
  }
  return totalStars;
};
```

--------------------------------

### Connect to Neon Postgres with Deno

Source: https://docs.val.town/guides/databases/neon-postgres.md

Uses the deno-postgres client to connect to a database via an environment variable. Ensure the environment variable key matches the one configured in your Val Town settings.

```ts
import { Client } from "https://deno.land/x/postgres/mod.ts";
const client = new Client(Deno.env.get("neon_url"));
await client.connect();
const result = await client.queryObject`select CURRENT_TIME;`;
console.log(result);
```

--------------------------------

### serveFile

Source: https://docs.val.town/reference/file-io.md

Serves a file from the val as an HTTP Response with the correct Content-Type header.

```APIDOC
## serveFile

### Description
Serves a file from the val as an HTTP Response with the correct Content-Type header.

### Parameters
- **path** (string) - Required - The file path to serve.
- **metaImportUrl** (string) - Optional - The import.meta.url to determine which val to serve from. Defaults to Deno.env.get("VALTOWN_ENTRYPOINT").

### Response
- **Returns** (Response) - An HTTP Response object containing the file content.
```

--------------------------------

### Initialize OpenAI with Personal API Key

Source: https://docs.val.town/reference/std/openai.md

Use the official npm:openai package with a custom OPENAI_API_KEY environment variable to bypass platform limits.

```ts
import { OpenAI } from "npm:openai";

const openai = new OpenAI();
```

--------------------------------

### Get email address for a file

Source: https://docs.val.town/reference/file-io.md

Retrieves the email address associated with a file that has an email trigger. Requires the file to have an email trigger configured and only supports UUID-based addresses.

```typescript
import { emailAddress } from "https://esm.town/v/std/utils/index.ts";

// Get the email address for a file with email trigger
const email = await emailAddress("/handlers/processEmail.ts");
console.log(email); // Returns: username-fileid@valtown.email
```

--------------------------------

### Authenticate with Val Town MCP

Source: https://docs.val.town/guides/prompting/openai-codex.md

Log in to the Val Town MCP server instance.

```bash
codex mcp login val_town
```

--------------------------------

### Query data from Supabase table

Source: https://docs.val.town/guides/databases/supabase.md

Retrieve data from your Supabase table using the .eq() method for filtering. This example selects specific columns and limits the results to one.

```typescript
import { createClient } from "https://esm.sh/@supabase/supabase-js@2";

const supabase = createClient(
  Deno.env.get("supabaseURL"),
  Deno.env.get("supabaseKey")
);
const { data, error } = await supabase
  .from("my_first_table")
  .select("name, data")
  .eq("name", "Alice")
  .limit(1);
if (error) {
  throw error;
}
console.log(data);
```

--------------------------------

### Check if a File is the Main Entry Point

Source: https://docs.val.town/reference/file-io.md

This function replaces Deno's `import.meta.main` in Val Town. Use it to conditionally execute code only when a file is run directly, similar to Python's `if __name__ == "__main__":`.

```typescript
import { isMain } from "https://esm.town/v/std/utils/index.ts";

if (isMain(import.meta.url)) {
  console.log("This file is being run directly");
  // Run main logic here
} else {
  console.log("This file is being imported");
  // Export functions/classes for use by other files
}
```

--------------------------------

### Implement Stripe Checkout

Source: https://docs.val.town/guides/stripe.md

Create a checkout session on the server and redirect the user to the Stripe-hosted payment page.

```typescript
// @ts-ignore
import { Stripe } from "npm:stripe";

const stripe = new Stripe(Deno.env.get("STRIPE_TEST_API_KEY"));

export default async function (req: Request): Promise<Response> {
  const url = new URL(req.url);
  if (url.pathname === "/") {
    return new Response(
      `<h1>Stripe Checkout Demo</h1>
      <form action="/create-checkout-session" method="POST">
      <input name="name" placeholder="t shirt">
      <input type="number" name="price" placeholder="$5">
      <button type="submit">Buy</button>
      </form>`,
      { headers: { "content-type": "text/html" } }
    );
  }
  if (url.pathname === "/create-checkout-session" && req.method === "POST") {
    const form = await req.formData();
    const name = form.get("name");
    const price = form.get("price");
    const session = await stripe.checkout.sessions.create({
      line_items: [
        {
          price_data: {
            currency: "usd",
            product_data: {
              name,
            },
            unit_amount: Number(price) * 100,
          },
          quantity: 1,
        },
      ],
      mode: "payment",
      success_url: `https://${url.host}/confirmation`,
      cancel_url: `https://${url.host}`,
      automatic_tax: { enabled: true },
    });
    return new Response(null, {
      status: 303,
      headers: {
        Location: session.url,
      },
    });
  }

  if (url.pathname === "/confirmation") {
    return new Response(`<h1>You paid!</h1>`, {
      headers: { "content-type": "text/html" },
    });
  }
}
```

--------------------------------

### Add Val Town MCP Server to Codex

Source: https://docs.val.town/guides/prompting/openai-codex.md

Register the Val Town MCP server URL with the Codex CLI.

```bash
codex mcp add val-town --url https://api.val.town/v3/mcp
```

--------------------------------

### Markdown Image Upload

Source: https://docs.val.town/reference/images.md

This is an example of how an image URL is automatically inserted into markdown after a drag-and-drop upload. Use this format when linking to images uploaded directly within Val Town's markdown editor.

```markdown
![supabase-valtown-webhook.png](https://imagedelivery.net/iHX6Ovru0O7AjmyT5yZRoA/fe4b1b4f-265a-4b53-1153-64fedb11d600/public)
```

--------------------------------

### Setting your Val Town API Token

Source: https://docs.val.town/reference/api/sdk.md

Configures the required authentication token in the terminal environment.

```bash
export VAL_TOWN_API_KEY=your api token…
```

--------------------------------

### Query Data from PlanetScale Table

Source: https://docs.val.town/guides/databases/planetscale

Query records from a PlanetScale table. The results are available in the `rows` property of the returned object. This example demonstrates fetching a specific item using a WHERE clause. Ensure environment variables are set.

```typescript
import { queryPlanetScale } from "https://esm.town/v/vtdocs/queryPlanetScale";

const results = await queryPlanetScale(
  {
    host: Deno.env.get("planetScaleHost"),
    username: Deno.env.get("planetScaleUsername"),
    password: Deno.env.get("planetScalePassword"),
  },
  `SELECT id, name, price FROM stock WHERE name=?`,
  ["banana"]
);
console.log(results.rows[0]);
```

--------------------------------

### Run a Val in Deno

Source: https://docs.val.town/guides/interop.md

Execute a public val directly using the Deno CLI and its module URL.

```sh
$ deno run https://esm.town/v/tmcw/randomVal
0.5133662021089374
```

--------------------------------

### Polling RSS Feeds

Source: https://docs.val.town/guides/rss.md

Use this example with a Cron trigger to poll RSS feeds at regular intervals. It checks for new items and sends an email notification if any are found. Ensure the `rssFeeds` object is populated with the feed names and URLs.

```typescript
import { email } from "https://esm.town/v/std/email?v=9";
import { newRSSItems } from "https://esm.town/v/stevekrouse/newRSSItems";
import { rssFeeds } from "https://esm.town/v/stevekrouse/rssFeeds";

export async function pollRSSFeeds({ lastRunAt }: Interval) {
  return Promise.all(
    Object.entries(rssFeeds).map(async ([name, url]) => {
      let items = await newRSSItems({
        url,
        lastRunAt,
      });
      if (items.length)
        await email({
          text: JSON.stringify(items, null, 2),
          subject: `New from ${name} RSS`,
        });
      return { name, items };
    })
  );
}
```

--------------------------------

### Watch for local changes

Source: https://docs.val.town/guides/prompting/cli.md

Use the `vt watch` command to automatically sync your local Val project changes to Val Town as you save files.

```bash
vt watch
```

--------------------------------

### List files using the SDK

Source: https://docs.val.town/reference/file-io.md

Retrieves a list of files from a val recursively.

```ts
import ValTown from "npm:@valtown/sdk";
const vt = new ValTown();
const val_id = "your-val-id-here";
const files = await Array.fromAsync(
  vt.vals.files.retrieve(id, {
    path: "",
    recursive: true,
  })
);
```

--------------------------------

### isMain

Source: https://docs.val.town/reference/file-io.md

Checks if the current file is the main entry point of the val, serving as a replacement for import.meta.main.

```APIDOC
## isMain

### Description
Checks if the current file is the main entry point of the val. This is a replacement for import.meta.main which is not available in Val Town's environment.

### Parameters
- **importMetaURL** (string) - Required - The import.meta.url of the current file.

### Usage Example
```ts
import { isMain } from "https://esm.town/v/std/utils/index.ts";

if (isMain(import.meta.url)) {
  console.log("This file is being run directly");
} else {
  console.log("This file is being imported");
}
```
```

--------------------------------

### Table creation

Source: https://docs.val.town/reference/std/sqlite/usage.md

Creates a table if it does not already exist.

```ts
import { sqlite } from "https://esm.town/v/std/sqlite/main.ts";

await sqlite.execute(`create table if not exists kv(
  key text unique,
  value text
)`);
```

--------------------------------

### Access permitted system information

Source: https://docs.val.town/troubleshooting/permission-errors.md

Demonstrates usage of allowed system information APIs within the sandbox.

```ts
import os from "node:os";
os.cpus();
os.homedir();
Deno.osRelease();
Deno.hostname();
```

--------------------------------

### Run a Private Val in Deno

Source: https://docs.val.town/guides/interop.md

Authenticate private val execution by providing an API token via the DENO_AUTH_TOKENS environment variable.

```sh
$ DENO_AUTH_TOKENS=xxx@esm.town deno run https://esm.town/v/tmcw/privateVal

Hello world!
```

--------------------------------

### Read a file using the SDK

Source: https://docs.val.town/reference/file-io.md

Retrieves the content of a file from a specific val using the Val Town SDK.

```ts
import ValTown from "npm:@valtown/sdk";
const vt = new ValTown();
const val_id = "your-val-id-here";
const response = await vt.vals.files.getContent(val_id, {
  path: "path/to/file.txt",
});
const content = await response.text();
console.log(content);
```

--------------------------------

### Serve a file as an HTTP response

Source: https://docs.val.town/reference/file-io.md

Serves a file from a val as an HTTP Response with the appropriate Content-Type header. Useful within web frameworks like Hono.

```typescript
import { serveFile } from "https://esm.town/v/std/utils/index.ts";

// In a Hono app - most common usage
app.get("/assets/*", async (c) => {
  return await serveFile(c.req.path);
});

// Explicit val specification
app.get("/assets/*", async (c) => {
  return await serveFile(c.req.path, import.meta.url);
});
```

--------------------------------

### Configure MCP Server for Cursor

Source: https://docs.val.town/guides/prompting/cursor.md

Add this configuration to your mcp.json file to enable Val Town tools in Cursor. Ensure you replace API_TOKEN_HERE with a valid token from your Val Town settings.

```json
{
  "mcpServers": {
    "val-town": {
      "url": "https://api.val.town/v3/mcp",
      "headers": {
        "Authorization": "Bearer API_TOKEN_HERE"
      }
    }
  }
}
```

--------------------------------

### Run a Val in Node.js

Source: https://docs.val.town/guides/interop.md

Execute a val in Node.js using the experimental network imports flag and an ESM-compatible file.

```js
// index.mjs
import rand from "https://esm.town/v/tmcw/randomVal";
console.log(rand);
```

```sh
$ node --experimental-network-imports index.mjs
0.4050279110448427
```

--------------------------------

### Create a new branch for Val changes

Source: https://docs.val.town/guides/prompting/cli.md

Optionally, use `vt checkout -b <branch>` to create a new branch for isolating changes to your Val project.

```bash
vt checkout -b <branch>
```

--------------------------------

### Importing NPM Modules

Source: https://docs.val.town/reference/version-control.md

Specify exact versions or version ranges for NPM modules using the npm: prefix.

```ts
import { min } from "npm:lodash-es@4.17.21";

// Or you can specify a version range, like
// you would in a package.json file:
import { min } from "npm:lodash-es@4";
```

--------------------------------

### List files by path using utils

Source: https://docs.val.town/reference/file-io.md

Lists files in a specific directory path within the current val.

```ts
import { listFilesByPath } from "https://esm.town/v/std/utils/index.ts";

// List files in a specific directory
const frontendFiles = await listFilesByPath("frontend/");
frontendFiles.forEach((file) => console.log(file.path));
```
Tokens:
Raw