\n {link}\n {markdown}\n

\n );\n}\n\nexport default async function(req: Request): Promise {\n const url = new URL(req.url);\n if (url.pathname === \"/\") {\n const files = await listFiles(import.meta.url);\n const posts = files.filter((file) => file.path.startsWith(\"posts/\"));\n const postContents = await Promise.all(\n posts.map(async (file) => readFile(file.path, import.meta.url)),\n );\n\n return html(\n

My blog!

This is my blog.

Posts

\n {postContents.map((markdown, i) => )}\n

,\n );\n }\n if (url.pathname.startsWith(\"/posts/\")) {\n const markdown = await readFile(url.pathname, import.meta.url);\n return html(\n

My blog!

\n {markdown}\n

,\n );\n }\n return new Response(\"Not found\", { status: 404 });\n}\n\nfunction html(children: React.ReactNode) {\n return new Response(\n renderToString(\n \n {children}\n ,\n ),\n {\n headers: {\n \"content-type\": \"text/html;\",\n },\n },\n );\n}","label",[150],"847f6192-1b37-11f0-9778-569c3dd06744","deno.json","847f6282-1b37-11f0-9778-569c3dd06744",3,["D",1744858570834],"{\n \"$schema\": \"https://raw.githubusercontent.com/denoland/deno/348900b8b79f4a434cab4c74b3bc8d4d2fa8ee74/cli/schemas/config-file.v1.json\",\n \"lock\": false,\n \"compilerOptions\": {\n \"noImplicitAny\": false,\n \"strict\": false,\n \"types\": [\n \"https://www.val.town/types/valtown.d.ts\"\n ],\n \"lib\": [\n \"dom\",\n \"dom.iterable\",\n \"dom.asynciterable\",\n \"deno.ns\",\n \"deno.unstable\"\n ]\n },\n \"lint\": {\n \"files\": {\n \"include\": [\n \"deno:/https/esm.town/**/*\"\n ]\n },\n \"rules\": {\n \"exclude\": [\n \"no-explicit-any\"\n ]\n }\n },\n \"node_modules_dir\": false,\n \"experimental\": {\n \"unstable-node-globals\": true,\n \"unstable-temporal\": true,\n \"unstable-worker-options\": true,\n \"unstable-sloppy-imports\": true\n }\n}",[160],"52c127da-1b37-11f0-9141-569c3dd06744","README.md","3a9357e0-e90c-42af-9508-1c0ce7d9a9e0",["D",1744858487353],"# 📖 myBlog\n\nA simple static blog.\n\n### 🚀 Getting Started\n\n- Click **Remix** on the top right to clone this project.\n\n### 📂 Adding Posts\n\n1. Navigate to the `/posts` directory.\n2. Create a new Markdown (`.md`) or `.mdx` file.\n3. Write your post and save the file.",[167],"52c1262c-1b37-11f0-9141-569c3dd06744","Layout.tsx","39797c14-1865-405b-b663-fbf3d1899c7a",["D",1744858487353],"script","/** @jsxImportSource npm:react@18.2.0 */\nimport type { ReactNode } from \"npm:react@18.2.0\";\n\nexport function Layout({ children }: { children: ReactNode }) {\n return (\n \n \n \n \n My blog\n \n \n \n {children}\n \n \n );\n}",[173],"8482434e-1b37-11f0-b1c4-569c3dd06744",".vtignore","848244f2-1b37-11f0-b1c4-569c3dd06744",4,["D",1744858570839],".git\n.DS_Store\nnode_modules\nvendor",[180],"52c12398-1b37-11f0-9141-569c3dd06744","posts","accc06dc-1d49-41da-b8cc-2e8b68adc2d7",["D",1744858487353],"directory",[187],"pulls","branches","forks","envVars",{"_199":62,"_201":62},"connections",{"_199":62,"_200":62},"count","unfilledCount","emptyCount",{"_42":186,"_32":187,"_30":188,"_151":-5,"_40":41,"_39":152,"_153":25,"_37":233,"_13":62,"_34":190,"_35":-5,"_24":48,"_157":-5,"_210":234,"_27":235},{"_42":225,"_32":226,"_30":227,"_151":188,"_40":41,"_39":228,"_153":48,"_37":229,"_13":152,"_34":20,"_35":230,"_24":48,"_157":-5,"_210":231,"_27":232},{"_42":179,"_32":180,"_30":181,"_151":-5,"_40":41,"_39":182,"_153":25,"_37":222,"_13":62,"_34":20,"_35":184,"_24":48,"_157":-5,"_210":223,"_27":224},{"_42":172,"_32":173,"_30":174,"_151":-5,"_40":41,"_39":152,"_153":48,"_37":219,"_13":62,"_34":176,"_35":177,"_24":48,"_157":-5,"_210":220,"_27":221},{"_42":166,"_32":167,"_30":168,"_151":-5,"_40":41,"_39":152,"_153":48,"_37":216,"_13":62,"_34":20,"_35":170,"_24":48,"_157":-5,"_210":217,"_27":218},{"_42":159,"_32":160,"_30":161,"_151":-5,"_40":41,"_39":162,"_153":48,"_37":213,"_13":62,"_34":20,"_35":164,"_24":48,"_157":-5,"_210":214,"_27":215},{"_42":149,"_32":150,"_30":56,"_151":-5,"_40":41,"_39":152,"_153":48,"_37":209,"_13":62,"_34":155,"_35":156,"_24":48,"_157":-5,"_210":211,"_27":212},["D",1744858487353],"children",[],[150],["D",1744858570834],[],[160],["D",1744858487353],[],[167],["D",1744858487353],[],[173],["D",1744858570839],[],[180],"9440c378-1b37-11f0-94f6-569c3dd06744","001-makingVtCli.md","847addd4-1b37-11f0-a750-569c3dd06744",5,["D",1744858597279],"![](https://wolf-mermelstein-personal-website.s3.us-east-2.amazonaws.com/example-watch.webm)\n\nIntroducing VT: the official command line tool to edit, manage, and begin val town projects right from your computer!\n\nVal town gives you a super fast, light, simple, and intuitive way to instantly create websites. But until now, this entire experience has been on a polished web platform. There's a lot of reasons to want to work on your Val Town projects locally. Maybe you want to work from the comfort of your favorite editor, whether that's vscode, with your favorite extensions, theme, and keybinds, or Neovim. Or you want to access powerful local devtools, which are increasingly AI powered ones like Claude Code or AI powered IDEs. Maybe you want to use `git`, or some other version control system out side of Val Town. Or maybe you just want to keep a back up of a Val Town project, or work offline. Now you can!\n\n# Finding the path\n\nThere's a lot of different paths we could take to engineer a local val town development experience.\n\n![Diagram from https://www.cs.cmu.edu/~./fp/courses/15213-s07/lectures/15-filesys/index.html](https://wolf-mermelstein-personal-website.s3.us-east-2.amazonaws.com/bcbdf72d-0875-4288-ab8c-3b06b1cace32.webp)\n\nOriginally, this project took the form of a fuse file system. Fuse is a Linux protocol that lets you implement arbitrary file systems in userspace. By implementing a fuse val town file system, all edits locally are instantly reflected on the val town website, and vice versa (if you update remotely, then if you try to save locally your editor will say something along the lines of \"more recent edits found, are you sure you want to write\"). Fuse is very powerful -- writes, reads, and all other file system syscalls can be handled with whatever response you want.\n\nThis project was `vtfs`, a project with the goal of exposing val town functionality through a file system. Originally it was a side project of mine, because \"can I write the code in neovim\" was the first question I asked myself when I first saw Val Town. I love the elegance of a file being a website, and thought it would be fun to be able to do a \"touch website.ts\" to create them, via the magic of fuse, and val town!\n\n[And so I built it](https://github.com/404wolf/valfs)! `valfs` was really cool: you'd run `vt mount [dir]` and you'd get a folder with all of your vals in it.\n\nVt was built written in `golang` with [`go-fuse`](https://github.com/hanwen/go-fuse), because, I didn't want to deal with C++ package management, and I wanted to try `go`.\n\n![](https://wolf-mermelstein-personal-website.s3.us-east-2.amazonaws.com/37c9a2a8-3f0a-4b52-a9c7-cf7c0cc0799b.webp)\n\nUnfortunately `vtfs` no longer works anymore and because of breaking API changes, and, while there was work in progress on `vtfs` to add support for val town projects, development has paused on the project in favor of `vt`.\n\nWe decided to rewrite it, mostly for compatability reasons. Linux offers native fuse support, but MacOS and Windows definitely do not. For Mac, there's a project called [MacFuse](https://macfuse.github.io/) that acts as a kernel extension to provide fuse support to Mac. However, it's not totally stable, and [Apple is deprecating kernel extensions](https://developer.apple.com/support/kernel-extensions/) and it may not be the best long term solution. There's a really cool project called [fuse-t](https://www.fuse-t.org/) that takes a different approach, where it implements the fuse protocol by forwarding fuse to NFS (network file system), a protocol that Macs do natively support.\n\nEven though it's a total rewrite, though, many design choices for `vt` came from `vtfs`.\n\n# Going Git\n\n`vt` is heavily inspired by both `git` and [gh](https://cli.github.com/), the github CLI. There's elements like `vt push` and pull that are very `git`ty, and things like `vt create` that act like `gh repo create`.\n\n![Gh browse](https://wolf-mermelstein-personal-website.s3.us-east-2.amazonaws.com/017b5db4-0379-4965-a94f-e9101a69b485.webp)\n\nOne handy `vt` command that we added is `vt browse`. `vt browse` opens up the current project in a web browser. As we work on improving hybrid workflows with the CLI and website, we will probably turn to `gh` to extend `vt browse`'s functionality.\n\n### The Meaning of `VT Pull` and `VT Push`\n\nUnlike `git`, where you have a `stage` and `commits`, `vt` only has a notion of `pushing` and `pulling`. This means that the local state could conflict in ways with the remote state that could result in changes that we can't reconsile: like, if you pull and you have newer changes locally, or If you push and there are newer changes in the remote.\n\n[We spent a while considering what pushing and pulling meant](https://github.com/val-town/vt/issues/45). The conclusion we came to:\n\n* `pushing` is a forceful procedure. When you push we ensure that the remote state matches the local state, and by the end of the push the remote state should match the local state with no changes to the local state. This might sound scary, but we do versioning for projects, so in the worst case you could revert to an earlier version on the website and pull.\n* `pulling` is a \"graceful\" procedure. When you pull, you may receive modifications, deletions, creations, or renames to local files. For all of these changes except creations, pulling warns the user that local changes will be lost, and you need to confirm to complete the pull. This is implemented internally by doing a \"dry\" pull and checking what changes would be made locally.\n\nThis means that the contract for push is \"push the local state to make sure the remote matches it\" and pull is \"get the remote state and make sure the local state matches it.\"\n\nSomething we get for free is `status`. `git status` looks at changes since the previous commit, but `vt status` is identical to `vt push --dry-run`, and shows you all the changes that would get pushed.\n\n### Beautiful Abstractions\n\nAs it turns out, many of the internal vt operations are able to easily piggyback off of one another. Like `vt push --dry-run` being the same as `vt status`, `vt pull` just does a `vt clone`, and then removes stuff that does not exist on the remote that still exists locally, or `vt checkout` is somewhat like `vt pull`-ing the branch you are trying to check out. These abstractions make testing and maintenance much easier.\n\n### Syncing\n\nOne idea that we had to solve this problem of \"the meaning of push and pull\" was to totally scrap both, and change the contract to \"sync to a consistent state.\" As it turns out, syncing really just redirects all the complexity, and is still quite complicated to implement.\n\nI spent a while designing an algorithm for syncing, where the primary \"building block\" of the algorithm was to \"walk\" through revisions and make changes to the local state incrementally. Syncing would start by pulling to incorporate all remote changes locally, and then push the remainder. It also would look at modification times to try to guess which update should be kept in the case of local/remote conflicts.\n\n```\nProcedure Sync:\n 1. Pull Updates from Remote\n - While current_version < latest_version:\n - Fetch the delta for current_version --> current_version + 1 \n\t from the remote.\n - Apply the delta:\n - New File:\n - If the file does not exist locally:\n - Create it.\n - Else:\n - Keep the newer one (compare btime or maybe mtime?).\n - Deleted File:\n - If the local mtime <= than the remote delete time:\n - Delete it locally.\n - Else:\n - Do nothing, keep the local file. We'll push it back later.\n - Modified File:\n - If modified locally:\n - Keep the newer modification.\n - Else:\n - Update the local file with the remote version.\n - Increment current_version.\n\n 2. Push Local Changes\n - For each file in the local vt directory:\n - If file.mtime > remote_file.updatedAt:\n - Upload the file.\n - If the file exists locally but not on the server:\n - Upload it.\n\n 3. Cleanup Remote Server, Fix Local State\n - For each file in the recursive vt server listing:\n - If it does not exist locally, delete it from the remote.\n - Update the local file's mtime to be the server's\n - Update version: current_version++ (should match remote_version++).\n```\n\nWorking on `vt`, I came across a lot of really cool abstractions\n\n## The Live Dev Experience\n\nOne of the most important use cases of `vt` is \"watch\" functionality. From the beginning, my plan for this was to implement \"git\" behavior first (pushing and pulling), and then just doing file system watching to add live syncing using [Deno.watchFs](https://docs.deno.com/api/deno/~/Deno.watchFs) to handle file system events.\n\n![](https://wolf-mermelstein-personal-website.s3.us-east-2.amazonaws.com/79892400-37e7-4ab3-a862-02b1ecb724ce.webp)\n\nOne particularly annoying challenge with `vt watch` was handling debouncing. Deno's standard library has an [async module](https://jsr.io/@std/async) that was super useful for implementing `vt watch`. `vt watch` works by doing a `push` initially, and then whenever local changes are made running another `vt push`. It sounds super simple!\n\nThe issue is that there's a lot of different things that could trigger a \"files were changed\" notification, and doing the push itself is one of them (the `.vt` folder has files internally that get updated on a push). Instead of working out the corner cases, I added a grace for post-pushing before we are able to detect file changes again.\n\nI also debounce the push. Initially, I did this so that if you are doing large amounts of file modifications we wait until you're done before starting the push, but it turns out this is more important because of how editors will create ephemeral temporary files during writes. Now, when you edit a file, the editor might create transient files, but as long as it gets rid of them within the debounce the final state that gets pushed is the one that does not include those temporary files.\n\n## Naming\n\n### Val Types\n\nOne of the initial concerns was how one could edit val metadata locally, if we are limited to the context of files.\n\n![](Screenshot%202025-04-16%20at%206.32.46%20PM.webp)\n\n`vtfs`'s approach to this was to pack all of the metadata for a val into the file corresponding to it. For Val Town projects, it's a bit more complex, because there's metadata specific to vals in the project, and metadata for the entire project itself too. We decided that, in general, changing val metadata and other uniquely val town attributes is something that we would leave to the website.\n\n`vtfs` would indicate the type of a given val locally as `foobar.H.tsx` (or, if verbose, `foobar.http.tsx`), which was a really nice pattern. If you wanted to change the type of a val, you could just rename it to `foobar.script.tsx`. This pattern, however, turns out not to work as well for projects because vals in projects generally are suffixed with `.tsx`, so you would end up with `foobar.http.tsx.tsx`, and it would get messy quickly -- and there were some issues with Vscode not liking `.script.tsx`.\n\nInstead of doing strict enforcement -- maintaining a 1:1 mapping of file extension to val type -- `vt` intuits the val type only on creation. If you create a `foobar.tsx`, `vt` sees `.tsx` and assumes it's a script. If you create `foobar_http.tsx` or `foobar.http.tsx`, `vt` sees `.tsx`, knows it's a val and not a file, and then guesses it's an `http` val. But it never will change it after the fact, so you can change `foobar.http.tsx` to be a script val on the website, and that's what it will continue to be going forward.\n\n## Renaming\n\nIt might seem simple at first, but if you think about it, detecting whether a file was renamed is actually really tricky. If we move `foo.ts` to `bar.ts` how do we know that it wasn't a `CREATE bar.ts` and `DELETE foo.ts`? Originally we didn't plan on adding rename detection support to `vt` because of all the complexity that comes with rename detection.\n\n![](https://wolf-mermelstein-personal-website.s3.us-east-2.amazonaws.com/blob_file_1744341763182_recording.gif)\n\nBut then we realized that, without rename detection, if you move a val with configuration -- like cron config, or custom endpoint HTTP vals, then doing the deletion/creation would cause you to lose all your config! And so, we added rename detection to `vt`.\n\nThe rename detection algorithm is a bit complicated -- it works by looking at all files that got deleted and that got created, and then considering a file as renamed if a created file is sufficiently similar to a file that got deleted. When iterating over created files to see if a deleted file is similar enough to one of them, we use some heuristics to filter out files that could not possibly be similar enough, like the file length. Then we compute the Levenshtein distance between a given deleted file and created file, and consider a given created file \"renamed\" if it is above some theshold similar to a deleted file, and if it is similar enough to multiple, then the one it is most similar to [as it turns out, Deno's standard library has a super efficient edit distance function](https://jsr.io/@std/text). Git does fancy [directory rename detection](https://git-scm.com/docs/directory-rename-detection/2.22.0), which is something that, at least for now, `vt` does not do.\n\nBecause rename detection is relatively expensive, it is internally implemented as an optional operation that doesn't always get used for every `vt` operation. For example, there isn't a lot of reason to do rename detection for `vt pull` -- it would really just be for reporting.\n\n## Blob Store\n\nFor `vtfs`, something I wanted to add early on was a way to \"mount\" your val town blob store so that you could view, edit, and organize your blobs. With fuse, there's a ton of flexibility on how to implement inodes. `go-fuse` provides a lot of nice abstractions. For totally static files like `deno.json` I was using the [MemRegularFile](https://github.com/hanwen/go-fuse/blob/v2.7.2/fs/mem.go#L17) helper, which makes it trivial to create an Inode with static text contents. For Vals, I was doing it more manually, implementing the read and write methods for a custom `ValFile` Inode myself. But for blobs, I wanted to handle reads and writes by streaming the relavent portions of the file.\n\nWhen implementing my own write callback for fuse, I would be handling requests to write data to a region of a file (like, write 0001010101 starting at index 22 bytes). Our `/v1/blob` endpoint is somewhat restrictive here. You can only write an entire file, or get an entire file. Handling this was really tricky -- I could start a new upload to upload the entire state of the file, with the new change made in the current write call, but if you're writing a lot of data to a file (like if you `cp bigFile.png` to the folder that I was using to represent your val town blobs), then there would typically be a burst of write requests to write to consecutive regions of the file.\n\nI spent a long time working on setting up a pipe where I would handle consecutive writes, writes that start at index i, end at index i+k, and then a new write that starts at index i+k+1, etc, as a special case. Eventually, I got something working!\n\nFor `vtfs` I was using [Openapi Generator](https://github.com/OpenAPITools/openapi-generator), and it turned out that Val Town's OpenAPI specification didn't accept file sizes on the order of my tests -- where the response would include the file size, it was an integer, not a `format: int64` (long).\n\n![Working piped blob uploads](Pasted%20image%2020250414162037.webp)\n\nMaintaining this, and getting writes to work non consecutively continued to prove a huge challenge. `valfs` blob read/write support was a fun challenge to work on, but was never totally reliable.\n",[],[187,226],["D",1744858487353],[203],[187],["D",1744858487353],{"_100":99,"_107":103},{"_100":99,"_101":-5,"_102":103,"_18":54,"_104":105,"_106":48},{"_13":85,"_32":86,"_42":41,"_87":43,"_88":89,"_90":91,"_92":50,"_93":94,"_95":96,"_97":44,"_98":99},"ctx",{"_78":-5,"_129":273,"_274":275,"_276":277,"_278":48,"_279":48,"_280":48,"_281":25,"_282":-5,"_283":-7,"_284":-7,"_285":62,"_286":48,"_287":48,"_288":-5,"_289":48,"_290":48,"_291":48,"_292":-5},"ENV",{"_244":245,"_246":247,"_248":86,"_249":250,"_251":252,"_253":254,"_255":256,"_257":258,"_259":260,"_261":262,"_263":264,"_265":266,"_267":268,"_269":270,"_271":272},"REACT_APP_SENTRY_DSN","https://586020d86f05489db63a554690acf1e9@o1398359.ingest.sentry.io/6724499","RENDER_GIT_COMMIT","e8c4b7030cb7600e4eb0736b15f422c8b8bd130f","RENDER_GIT_BRANCH","POSTHOG_API_TOKEN","phc_nmoyuAkStEZuUp69rYlg1DZgrIt19Gx0Y4Hwf8tGgJP","POSTHOG_API_HOST","https://wart.val.town","WEB_API_TEMPLATE","https://{val}.web.val.run","APP_URL","https://www.val.town","MODULE_URL","https://esm.town","VANITY_WEB_API_TEMPLATE","https://{label}.val.run/","DENOLS_URL","https://lsp.val.town","NODE_ENV","production","CLOUDFLARE_TURNSTILE_SITE_KEY","0x4AAAAAACtaIZJH7s9rBMZ6","GOOGLE_CLIENT_ID","875989696899-jtsqkhlbdv5jrlsk8631p7ipjg3c6o62.apps.googleusercontent.com","STRIPE_PUBLISHABLE_KEY","pk_live_51N2zvWEpZTTLipIkVEwXrUG9AT0yeOOEYxszarZT1jpsZV58Ly6wlg3SltZpHN26CUalOBmUSY7adQRQiSkCZz2500qSXNkf8Y","API_URL","https://api.val.town",[],"preferencesKeybindings","default","preferencesTheme","light","preferencesFixers","preferencesCopilot","preferencesSelectionAi","preferencesCloseBrackets","preferencesChatPanelState","preferencesDprint","preferencesDenofmt","notificationCount","flagDenols","isBusinessOrgMember","businessOrgHandle","isBusinessOrgAdmin","isHigherTownieTier","navCollapsed","currentOrgId"]

Diff · v7