Val Town Code SearchReturn to Val Town

8Today, we’re unifying our two primitives — *vals* and *projects* — into a single primitive: the **val**, with the best features of both.
9
10Historically, vals have been simple and lightweight, but limited to a single file. This upgrade will preserve the elegant spirit of our platform while supporting more complex code and collaborative workflows. This upgrade will help you create bigger things on Val Town – APIs, internal tools, fullstack apps, blogs ([like this one](https://www.val.town/x/valdottown/blog)), and much more – without sacrificing the simplicity you've always loved about vals.
11
12*Legacy vals* will temporarily become *projects* during this migration. Post-migration, the concept of *projects* will disappear entirely — leaving only upgraded *vals*. In short: *legacy vals* → *projects* → *vals*.
16For most users, no upgrade action is required. We’ll auto-migrate your vals next week. All existing HTTP endpoints, crons, email handlers, and custom domains will be preserved.
17
18For those with mission-critical vals or who use our API to edit or create vals, you can start upgrading your legacy vals today and integrating with our updated API.
19
20- **April 23, 2025** – Announcement of changes & API deprecations.
21- **April 30, 2025** – All remaining *legacy vals* auto-upgraded. Deprecated API routes become read-only.
22- **May 1, 2025** – The term *projects* will no longer exist — everything will simply be a *val*.
23
35[See more details in our docs.](https://docs.val.town/upgrading/legacy-vals)
36
37## API Changes
38
39Today, we're introducing the following API routes:
40
41```bash
73```
74
75View our [updated API reference here](https://docs.val.town/openapi).
76
77All `v1/vals` API routes become read-only on **April 30, 2025**. If you rely on *writing* to those routes, please upgrade to our new `v2/vals` API. All deprecated API routes will continue serving historical legacy val data.
78
79### SDK changes
85
861. Upgrade your mission-critical vals early.
872. Update your Val Town API & SDK usage to `/v2` routes.
883. All remaining legacy vals migrate on **April 30, 2025**.
894. Migration completes on **May 1, 2025**.

2import { useAuth } from "./useAuth.tsx";
3
4const PROJECT_ENDPOINT = "/api/project";
5const FILES_ENDPOINT = "/api/project-files";
6
7export function useProject (projectId: string, branchId?: string) {

2import { useAuth } from "./useAuth.tsx";
3
4const ENDPOINT = "/api/projects-loader";
5
6export function useProjects () {

3import { useAuth } from "./useAuth.tsx";
4
5const ENDPOINT = "/api/create-project";
6
7export function useCreateProject () {

2import { useAuth } from "./useAuth.tsx";
3
4const ENDPOINT = "/api/create-branch";
5
6export function useCreateBranch (projectId: string) {

6  project: any;
7  branchId: string | undefined;
8  anthropicApiKey: string;
9  bearerToken: string;
10  selectedFiles: string[];
16  project,
17  branchId,
18  anthropicApiKey,
19  bearerToken,
20  selectedFiles,
37    status,
38  } = useChat({
39    api: "/api/send-message",
40    body: {
41      project,
42      branchId,
43      anthropicApiKey,
44      selectedFiles,
45      images: images

2import { useAuth } from "./useAuth.tsx";
3
4const ENDPOINT = "/api/project-branches";
5
6export function useBranches (projectId: string) {

3
4const TOKEN_KEY = "bearer";
5const ANTHROPIC_KEY = "anthropic_api_key";
6
7export function useAuth() {
8  const [token, setToken, removeToken] = useLocalStorage(TOKEN_KEY, "");
9  const [anthropicApiKey, setAnthropicApiKey, removeAnthropicApiKey] = useLocalStorage(ANTHROPIC_KEY, "");
10  const [error, setError] = useState(null);
11
12  const isAuthenticated = !!token;
13
14  const authenticate = async (valTownAPIKey: string, anthropicKey: string) => {
15    // replace all this with oauth when it's ready
16    try {
17      const res = await fetch("/api/user", {
18        headers: {
19          "Authorization": "Bearer " + valTownAPIKey,
20        },
21      });
25        setError(data.error);
26        removeToken();
27        removeAnthropicApiKey();
28        return;
29      }
30      setError(null);
31      setToken(valTownAPIKey);
32      setAnthropicApiKey(anthropicKey);
33    } catch (e) {
34      console.error(e);
35      setError(e.error);
36      removeToken();
37      removeAnthropicApiKey();
38    }
39  };
41  const logOut = () => {
42    removeToken();
43    removeAnthropicApiKey();
44  };
45
50    logOut,
51    token,
52    anthropicApiKey,
53  };
54}

76      SUM(num_images) as total_images
77    FROM ${USAGE_TABLE}
78    WHERE our_api_token = 1
79    GROUP BY user_id, username
80    ORDER BY total_price DESC
256              <th>Finish</th>
257              <th>Images</th>
258              <th>Our API</th>
259            </tr>
260          </thead>
276                <td>${row.finish_reason}</td>
277                <td>${formatNumber(row.num_images)}</td>
278                <td>${formatBoolean(row.our_api_token)}</td>
279              </tr>
280            `).join("")

13- Generate code in TypeScript or TSX
14- Add appropriate TypeScript types and interfaces for all data structures
15- Prefer official SDKs or libraries than writing API calls directly
16- Ask the user to supply API or library documentation if you are at all unsure about it
17- **Never bake in secrets into the code** - always use environment variables
18- Include comments explaining complex logic (avoid commenting obvious operations)
23### 1. HTTP Trigger
24
25- Create web APIs and endpoints
26- Handle HTTP requests and responses
27- Example structure:
167However, it's *extremely importing* to note that `parseProject` and other Standard Library utilities ONLY RUN ON THE SERVER.
168If you need access to this data on the client, run it in the server and pass it to the client by splicing it into the HTML page
169or by making an API request for it.
170
171## Val Town Platform Specifics
175- **AI Image:** To inline generate an AI image use: `<img src="https://maxm-imggenurl.web.val.run/the-description-of-your-image" />`
176- **Storage:** DO NOT use the Deno KV module for storage
177- **Browser APIs:** DO NOT use the `alert()`, `prompt()`, or `confirm()` methods
178- **Weather Data:** Use open-meteo for weather data (doesn't require API keys) unless otherwise specified
179- **View Source:** Add a view source link by importing & using `import.meta.url.replace("ems.sh", "val.town)"` (or passing this data to the client) and include `target="_top"` attribute
180- **Error Debugging:** Add `<script src="https://esm.town/v/std/catch"></script>` to HTML to capture client-side errors
181- **Error Handling:** Only use try...catch when there's a clear local resolution; Avoid catches that merely log or return 500s. Let errors bubble up with full context
182- **Environment Variables:** Use `Deno.env.get('keyname')` when you need to, but generally prefer APIs that don't require keys
183- **Imports:** Use `https://esm.sh` for npm and Deno dependencies to ensure compatibility on server and browser
184- **Storage Strategy:** Only use backend storage if explicitly required; prefer simple static client-side sites
218### Backend (Hono) Best Practices
219
220- Hono is the recommended API framework
221- Main entry point should be `backend/index.ts`
222- **Static asset serving:** Use the utility functions to read and serve project files:
242  });
243  ```
244- Create RESTful API routes for CRUD operations
245- Always include this snippet at the top-level Hono app to re-throwing errors to see full stack traces:
246  ```ts
279   - For files in the project, use `readFile` helpers
280
2815. **API Design:**
282   - `fetch` handler is the entry point for HTTP vals
283   - Run the Hono app with `export default app.fetch // This is the entry point for HTTP vals`