Full Width [alt+shift+f] Shortcuts [alt+shift+k]
Sign Up [alt+shift+s] Log In [alt+shift+l]
1

epanet-js

from Tom MacWright [alt+shift+b] in programming

epanet-js is a new web application that combines modern web maps with the industry-standard EPANET hydraulic simulation algorithm. It’s for people planning and updating water utility systems: connecting pipes and pressures and figuring out what will happen. It’s a problem area that I’m totally fascinated by and know very little about. It’s made by the folks from Iterating - Luke Butler and Sam Payá, who are experts in the field. If you’ve been following along with my blog and projects, you might notice something familiar about this screenshot of epanet-js: Yep! A lifetime ago, I built a company and product called Placemark, which was a tool for creating and editing map data. When the business part didn’t work out, I published a free-to-use version of Placemark and made the code open source. I chose a very permissive license for the code: the MIT license. I wanted to let anything happen, including - especially - people creating paid products with the code. It’s hard to explain to people outside of the world of open source that folks building a business with the help of my code is the dream. Partly it’s that ‘being helpful’ is one of the goals in life that never gets old. The other part is that most software becomes obsolete and abandoned quickly. Creating software with any legacy is rare and something to celebrate. Plus, Placemark was a general purpose tool in search of a successful niche: I never figured out what that niche was. I had a lot of learning to do about product-market-fit. But hydraulic simulation is a real market, and these folks are real experts. There are other markets like this, I’m sure, and using Placemark code as a base could be a good way to jumpstart those companies - it’s not perfect, as I’ve documented extensively, but it could be good as a first step. And the folks at Iterating have even contributed changes upstream to the open source Placemark codebase, but that isn’t required by the MIT license at all: that’s just because they’re cool...
3rd Jul 2025

Stay updated

Get a weekly newsletter with the top 5 articles worth reading every week.

More from Tom MacWright

Cycling Vermont

In October I rode the Green Mountain Gravel Growler route in Vermont with a few close friends. It’s a route curated by bikepacking.com that consists of back roads, dirt roads, and single track trails. It wasn’t as blissfully car-free as the C&O Canal or the loop around Lake Konstanz that I rode earlier this year, but in exchange for sharing the road occasionally, we got loads of variety and beautiful hills to climb up and coast down. As the name implies, the route is structured around breweries. We only did half because vacation time is scarce, but still managed to hit some good ones. The first night’s, in Burlington, was Foam Brewers. I had the “Tally Mark” altbier, which tasted like a cigar, in a good way. We didn’t get much time to explore Burlington. We did see the world’s tallest filing cabinet. The first day of riding was from Burlington to Stowe, with stops at The Bidwell for food, The Tropic for a mid-ride drink, and ending at The Alchemist. About 50 miles, and 3,700 feet of climbing. Places like The Alchemist are impossibly nice: sunshine, babies and puppies crawling in the grass, happy people playing corn hole. The delirious happiness of finishing a long day in the saddle makes it all even more saturated and exuberant. I was feeling pretty good on the bike, most of the ergonomics were working. The only gear tweak that this trip will inspire is sticking to fancy cycling bibs (shorts): Ornot, to be specific, instead of trying to scrape by with the cheap stuff, which for me is The Black Bibs. The Alchemist’s “Heady Topper” is like drinking a flat white made out of hops. .up{display:grid;grid-template-columns:1fr 1fr 1fr;gap:10px;line-height:0} Weather was perfect for almost the entire trip, and the route was pretty clear and empty. We mostly encountered locals riding casually, casually passing us on the way up some big trail. Vermonters are strong riders. The second day would be about 44 miles of riding and well over 4,200 feet of elevation. At this point everyone was feeling it: we’re New Yorkers and a lot of the biggest rides up till this point have been pretty flat. The total elevation change for the C&O Canal ride we did was 605 feet over 185 miles. Riding Bear Mountain and the Goldens Bridge loop helped with training, but nothing near the city can match the relentless climbing in Vermont. I expect hills to crest when there’s a turn in the road, but Vermont doesn’t follow that rule. But, every hill ends eventually. I only had to walk up one, and that was because it was so steep that I couldn’t get traction and not wheelie at the same time. To make this all easier, we weren’t camping at all, just staying at nice places and sleeping in real beds. With the quickly changing weather, camping in the cold would’ve been pretty tough. So that meant more room for changes of clothes and creature comforts. Places to stay in Burlington, Stowe, Hardwick, and Montpelier are pretty scarce though, and tended to be at the very top of hills. Seemed like everything was at the top of the hill, especially… Where The Alchemist was a casual, hippie-inflected destination, Hill Farmstead was like an elusive vineyard that happened to brew beer. And it’s at the top of a hill, of course. Like everywhere else, there were a few other people who had also biked to the hill, and lots of families, dogs, and fleece jackets. They had a food truck outside which whipped up an excellent, fairly spicy vegan burrito for me. Timing for this trip was tight, and rushing to arrive at a brewery before close had a kind of reality-TV greatest race feel to it. We were going to Hill Farmstead on a Sunday, and their hours on Sundays are 11:30-3pm. They close at three! And they don’t re-open, that’s just it. The rest of the week the bar closes at 5: it’s an exclusively day-drinking oriented outlet. But we made it, and made it to Hardwick, where the local Positive Pie location had a spectacular beer selection and surprisingly vegan-friendly menu. This was my first time in Vermont, encountering its specific brand of rural living. Many people were so open and welcoming to us, asking about the route and complimenting our endurance like proud parents. This, even though it was nearly peak tourist season and they probably get plenty of other people following the same directions. One stop in particular, sticks in my memory, the Maple Corner Community Store. If you look at the full span here: this place is a grocery store, deli, coffee shop, live music venue, bar, as well as the post office. Plus it has a little free library out front, and carries a selection of books written by local authors and signs for plays written by local playwrights that are performed nearby. It’s hard to even comprehend the level of integrated community-hub joy in this place. And, for me, they had a world-class selection of vegan snacks. The few odd interactions with Vermonters were all about land: their private land, and that we should stay off it. Not that we ever were on it - we were staying in houses and riding on public roads. But still we got reminded not to veer off and ride through apple orchards or lawns. In one sense this is a funny inverse of cities, where people control such little territory, but here the average homeowner has acres upon acres. But land rules in Vermont are very unusual: the constitution allows people to hunt, fish, and trap on other people’s private land unless it’s posted that the land doesn’t permit it, and the rules around posting are contentious. I’d be watchful too if people could just hike to my backyard and kill a deer. Then we were headed back on the Amtrak from Montpelier. It’s such a perk to be able to do this kind of trip without renting or using a car at all, just riding to and from train stations. Amtrak’s train ticket guarantees a spot for the bike, but it is always stressful and rushed getting bikes on & off. We only completed the first half of this trip - Burlington-Stowe-Hardwick-Montpelier, so there’s another Vermont trip in the future. Maybe next year! It was really spectacular. The hills were tough, but it was all worth it.

yesterday • 1 votes
Recently

September was another big month for my life, mostly for me offline. Another good month for bicycle riding, seeing more of the trails on Randalls and Wards Islands. The New York area has taught me a few things about islands and one of them is that they're very fungible. On a map, Randalls and Wards Islands look one one island because they're "conjoined". They were conjoined on purpose: they used to be two, with a bridge and everything. But then in 1955 the government announced they wanted to join up the islands "by allowing private contractors to dump debris within Little Hell Gate for free" (!) Photo from From City of New York Department of Parks: 28 Years of Progress, scanned by Erica Fischer (!) CC BY SA 2.0 The opposite happened with Fire Island: it was one island for a while until 2012, and Hurricane Sandy broke it back into two. Photo from USGS, PD Dump trash to combine islands, dump water from the sky to divide them. That's just how life is. .two-up{display:grid;grid-template-columns:1fr 1fr;gap:10px} Listening I watched Magnolia this month and finally got the hype around Aimee Mann. It's a little frustrating that the songs from the film aren't on And a throwback: Dusty Springfield's version of When the Love Light Starts Shining Through His Eyes. Originally recorded by the Supremes and forgive me for highlighting the blue-eyed soul version of this song but it's so driving and urgent in a way that most of the other versions aren't, it's such a good slice of that very particular rushing rhythm of the era. Reading On a meta-level: I'm getting pulled back to Instapaper from Readeck, because I rely on offline reading so often and unfortunately the Readeck iOS offline mode is unreliable. It is open source and I should contribute and in all likelihood the issue will get fixed, but in the meantime I need something to look at on the subway. Reading: I enjoyed Spiral's launch post a lot, as well as turbopuffer's post about their refactoring. Database companies in the AI-adjacent space are a nice hybrid kind of reading, still concerned with architecture and a little more grounded than a lot of the "big idea" or marketing-centric stuff that I read from AI labs. I also liked Charles Broskoski's "Personal Business" essay (one of the are.na founders). And I've been really liking reading Work by Bud Smith. Review of that soon. Otherwise The end of October will be even more packed than September for me, so if I don't post, don't worry, I'm not dead, I'm partying.

1st Oct 2026 • 1 votes
Recently

I skipped August's Recently because this summer has been relentless, mostly in the positive sense. July and August were filled with bike rides, 5K races, friends in town, life changes and logistics. For a friend's birthday, we rode the rickety Coney Island Cyclone, which was faster and more intense than I remembered it. But it's been 18 years since the last injury on the coaster, and the rider was partly at fault: good enough for me. .two-up{display:grid;grid-template-columns:1fr 1fr;gap:10px} I rode my first proper randonneuring ride: 200km (124mi) to all of the beaches around Brooklyn. It was pretty challenging, as you'd expect, but I didn't 'find my limit' for endurance, but I did find my limit in terms of how many gels & ride-nutrition packets I could consume before sugar becomes repulsive. I do still heartily endorse maple syrup packets for ride nutrition: compared to the space-age fuels that all taste like fruit or coffee, it's an identifiable substance that tastes like you'd expect. And, not pictured, but I ran a bunch of 5Ks. Haven't hit my goal this year of going sub-20, but got close in the last one - 20:15. I'm not giving up yet, because the weather is getting better and Brooklyn has a lot of 5K options. Listening Hot Creek by Duffy x Uhlmann Duffy x Uhlmann has been in my rotation for a year now and the new album has all the things I like from the combination. This and Shrunken Elvis go along well together and both have been hits at dinner parties. This album from Frances Quinlan, the frontperson of Hop Along, went under the radar, but it's so good. I've also been playing Hop Along's send album Get Disowned. I really like everything that this band has put out. It's a product of Philadelphia but I hear some of the elements that drew me to DC post-punk in the turn-on-a-dime songwriting. Get Disowned by Hop Along Watching This video, 'The surprising truth about what motivates us', is kind of an artifact of the 'Obamaverse', as one of my friends would put it. It's by Daniel Pink, a writer-speaker-self-help kind of guy, and it's accompanied by one of those realtime hand-illustrations. There are lots of reasons to tune it out as YouTube filler. Still, I thought it was pretty cool for two reasons: first, it connected directly with Andrew Kelley's video, which is the next one. And it connects with my feelings about incentives and how most simple incentives are counterproductive. And second, the drawing is real. I'm so used to the artificial version of this visual style that it took a minutes to realize that the it wasn't AI or some 'drawing hand' style of video essay, it was a real person making quite nice illustrations: specifically Andrew Park. Found myself nodding along to every bit of this interview with Andrew Kelley. His values and motivation are so nice to encounter in this current phase of tech. He's kind of a role model, which is something that I used to find trite in my early career but I'm coming around to. As Adam Neely pointed out in his video, a lot of the people heavily using Suno (an AI music tool) could not cite any role models, and defaulted to a sort of enclosed, self-centered stance. I see this with engineering too: it's hard to discern what values or talents the people at 'the forefront of the industry' have that I want. Finding personal qualities as something to imitate instead of desires and possessions (cue the segue into Girard's Memetic theory) seems like a better way to live. Reading What strengthens a relationship? Almost always, it is personal investment. Perhaps an AI agent might be better at predicting what my father will want for his birthday than I am, but it definitionally cannot give him my time and consideration. Love is not just a feeling; it is a way of paying attention. Elizabeth Lopatto in The Verge picks apart Mark Zuckerberg's weird, sad view of humanity. It's worth a read even just for the incredible opening anecdote. Home of the titular 100 foot waves. Which existed when I was a kid of course, but the larger world didn’t know about them yet. They were our secret. My grandfather and I would walk to the lighthouse and watch the waves hitting against the cliffs and he’d tell me that these were the biggest waves in the world. I didn’t believe him, of course. I thought it was standard grandpa hyperbole. But I also didn’t want to believe that I was seeing the biggest of anything. Not yet. I wanted the really great things to be in the future. Something to aim for. Which means I missed out on some great things that were right in front of me. Mike Monteiro's newsletter is always beautiful and melancholy, and this is a really nice edition of it. I read and highlighted a few other articles but they were all saying things about AI, mostly about how it makes the world worse and makes people feel bad. I won't add those to the pile because I don't want that kind of content to dominate what I mention, even if it does dominate what I read. Elsewhere For the Val Town blog, I wrote about our experience with the bug bounty program. It's been a very interesting experience. Val Town has a pretty difficult security surface: in contrast to Mapbox, which was mostly a read-only API, it's a very read-write system with many access controls. At the center of the product is a sandbox that we want to keep secure. And because we're living in the AI age, a single bit of functionality can be exposed via REST API, React Router loaders, tRPC, and MCP. Building a model layer and a shared authorization layer - modeled after Oso - has helped a bit. But the reports still come in. It's pretty wild how AI factors into it: I'd say that 100% of the vulnerability reports used AI to write the report itself. From the best reporters, the vulnerabilities come with screen recordings and evidence, and it's clearly not all-robot. But - I suspect that other people manning help desks & bug bounty programs know this experience - it's jarring to go three replies into an email conversation with someone and they suddenly stop using an LLM to write their emails and the voice completely changes, from hyper-literate to abbreviated and misspelled. I also wrote about our new authentication scheme that makes vals require login and makes it possible to manage permissions to val applications, not just their code. It was pretty fun to implement, and the sixth or seventh time working with HMAC schemes I'm starting to get a natural grasp on them.

1st Sep 2026
Technology optimism hour

Back in 2022, I wrote Web technology optimism hour, highlighting the things I thought were cool about the state of technology. Time flies. Let's do it again. It's still easy to be pessimistic, but it's nice to mine your feelings for the positive ones. The elephant in the room is AI, but I don't feel like throwing another post into the gravity field of that topic. Without further adieu: TypeScript 7 It's here, finally, and it's faster. In the last edition, one of the headings was "Rust and Go based tools are making TypeScript development faster." At that point we had a few upstart projects for minifying, transpiling, and bundling TypeScript. Those tools have become standard-issue. But TypeScript, the actual type-checking of the language and the language tooling in editors, was still a bottleneck. There was exactly one implementation of the TypeScript type checker, and it was implemented in TypeScript, so it ran at JavaScript speeds and had limited ability to become multi-threaded. Unfortunately there's still only one game in town for TypeScript type checkers: it's still just Microsoft. But they rewrote TypeScript in Go for TypeScript 7 and it's much, much faster. This is one of the most noticeable changes to my day-to-day coding in a while. Plus, even better: TypeScript 7 supports the Language Server Protocol! As I wrote about in 2024, Microsoft invented TypeScript and also the Language Server Protocol, but TypeScript never implemented the Language Server Protocol. So there was no standard way for other editors, other than Microsoft's VS Code, to provide language tooling for TypeScript. This was suspicious behavior because of the company's history. But now: it just works. Neovim can support TypeScript 7 with its built-in Language Server support instead of someone wrapping the VSCode extension in an LS-protocol shell. So: a big win. Hooray for the new TypeScript: it's faster, it supports open standards, and now there are two TypeScript implementations. Now all we need is one that's made by someone who doesn't work at Microsoft. The Effect ecosystem is exciting I've been writing little development logs about Effect over the last year or two. I'm excited about Effect. It's a big, all-encompassing system, but I think it has a lot of potential and is arriving at exactly the right time. This is an era of supply-chain risk and I think there is, and should be, a swing away from the tiny module ecosystems in NPM. Software that's composed of hundreds of little modules from hundreds of authors is a lovely idea that doesn't work with malicious actors. The swing is toward larger, buttoned-up libraries, and Effect is really well-positioned for that. It has type validation, observability, state management, fancy data types, and lots of functional programming helpers all under one roof, in one package that's pretty well-maintained and heavily tested. It's also very, very typed, which makes it safer to use at scale. And it makes limits a lot easier: you can just stick an Effect.timeout on anything and prevent network requests or database queries or anything else from taking too long. The same with concurrency, it's very easy to limit concurrency. It's ready for a very uncertain world where you have to validate and be careful about everything. But at the same time, it's fun to use, if you're that kind of person, which I am. Bluesky and Mastodon are successful, meaningfully decentralized systems I use Bluesky and Mastodon all the time and both just work. They don't feel like tech demos, it's not all nerds using them. The uptime is pretty good, the featureset doesn't seem limited by the technology choices. And yet both are legitimately decentralized (in different ways) networks, with really interesting ideas about security, privacy, and community systems. Bluesky is aggressively building out its protocol as an independent technology from the social network, and as I learned at their conference, there are lots of creative people building on the technology. There's a big gap between a cool tech demo and a user-friendly popular service, and both of these have bridged it. It's exciting, and shows that you don't have to accept a bad set of tradeoffs to make tech that's both principled and popular. Signal, WhatsApp, iMessage, and RCS are meaningfully secure messaging platforms I want to just celebrate the end of a technology: SMS. It's so good that people don't use SMS anymore: it was needlessly expensive and extremely insecure. My texts with friends are almost exclusively on Signal & iMessage, and occasionally WhatsApp. Now, WhatsApp is a mixed bag and nothing's perfect, but it's cool that the secure options recommended by the EFF and other sources are also popular options that people use every day. That's also pretty important from a privacy standard: having Signal installed on your phone is normal because it has a wide userbase, but the same would not be true if it was only used by people attending protests and being wary of government surveillance. Hardware update cycles are slowing People are hanging on to their phones and computers for longer. I'm part of this trend - my iPhone hit its fourth birthday, and I have no reason to even think about replacing this computer. With the exception of their batteries, modern laptops and phones are robust: they're water-resistant, made of durable materials, and basically just work. You could read the same data differently: maybe people are upgrading slower because they have less disposable income. I'm not sure that's true. But either way, it's good that upgrade cycles are longer: it means less e-waste, less pollution, less churn overall.

14th Aug 2026 • 1 votes
Recently

June was a big month: I went to Porto & Lisbon, and had a lot of life stuff happen. I'll get into the trip once I get my rolls of film developed. Three rolls at a new photo developing place: fingers crossed! Reading I finished reading Intermezzo (of the bag) and it was fantastic. I've always liked Sally Rooney's books but this was the one where the writing style really clicked. Also, The Vegan. Meh. I read Patricia Lockwood's 'A Tradcath Wedding' via Perfect Sentences but found an additional sentence to be perfect: Whenever they rang the chimes, which seemed to be every four seconds or so, a toddler screamed ‘WOW A BELL!’ to the visible displeasure of the celebrants – though isn’t the entire point of the ritual that you’re supposed to be that awestruck every time? Patricia Lockwood is the funniest writer I've read. You cannot grow a pumpkin, but you can improve the odds. Taylor's 'You Cannot Grow a Pumpkin' is a fantastic little prose poem of sorts. Watching I'm always trying to find a 'romp' when it comes to movies. Something lighthearted, pretty easy to watch, so on. We watched The Pink Panther this month and it is a perfect example of the genre. The inspiration for the watch came from the hamburger scene: But there's so much more of this kind of thing in the movie, little bits and physical comedy. Oh, and I also watched The Departed, which everyone says is good and is good. Elsewhere I wrote Accidental Anonymity on the micro blog, and it stirred up some discussion on Bluesky as well as at least one blog response. It was kind of an angry piece, as I said at the start. I will keep trying to stay out of the trap of writing about that topic all the time. Listening The only album I bought this month was Songs of Her's by Her's, which is fine. I wish I had something more profound to say about it given how the band met an unbelievably tragic end. Maybe more influential than that was Know Your Enemy's recent podcasts, especially this one about the pope's encyclical. I've really grown to love that podcast, and it has been part of me intellectually reconnecting with, but not readopting, Catholicism. Art Here's some art I really liked this month: This Hockney piece called 'Picture Emphasizing Stillness' from 1962 was at the MAC/CCB museum in Lisbon. Via Tim Babb, I enjoyed finding Tomás Sánchez's work.

1st Jul 2026 • 1 votes

More in programming

TokyoDev Welcomes Its Head of Operations

TokyoDev has grown substantially over the past few years. We’ve expanded our community, dramatically increased the scope and frequency of our events, and have curated a library of articles for international developers. Despite all that, the way we run the business hasn’t changed much. I’ve continued to coordinate most of these activities myself, making the final decisions and keeping everything connected. In short, TokyoDev cannot run without my daily input. That approach worked well when TokyoDev was smaller, but it’s increasingly limiting how much we can accomplish. To help the business grow further, I wanted to find someone to take over some of my responsibilities and bring a fresh perspective. This is a significant step for me personally, as while I have worked with many contractors over the years, I have never actually hired a regular employee. Most importantly, I wanted to ensure that this person was someone I could trust to understand what TokyoDev stands for, and to make decisions in line with our philosophy. So I’m happy to announce that Scott Rothrock is joining TokyoDev full time as our Head of Operations. About Scott Scott has lived in Japan for nearly 20 years and has worked as a software engineer in multiple industries and environments, including small Japanese-owned businesses, overseas employers, and international companies based in Japan. Until the end of October 2026, he was the head of the Japan Markets team at Kraken Technologies, where he led an international team of software engineers in delivering complicated, regulated products on strict timelines for Japanese electricity and gas retailers, while also ensuring compliance with evolving organizational and global standards. He’s made a name for himself both inside and outside Japan as a kind, effective mentor who can cultivate great engineers and leaders. Scott’s previous role in TokyoDev Some of you may already know Scott in another capacity, as he has been involved with TokyoDev since 2022. He began as a community volunteer and later became our community manager, which also included responsibilities such as managing our article pipeline from submission to publishing. When I created TokyoDev’s Discord, I had no previous experience running an online community. Scott joined soon after I started and began helping other members, stepping in when people behaved inappropriately, and configuring our roles and permissions and safety features. I was impressed by his initiative and asked him to become an official moderator in January 2023. Outside of his role as a moderator, Scott has always pushed TokyoDev to grow; for example, he arranged internet events such as livestreamed AMAs and interviews. He organized TokyoDev’s first meetup as a volunteer in February 2023, which taught me that there was interest in TokyoDev events outside of the internet. By the end of 2023, I had brought him on as our part-time community manager. What I saw throughout his tenure was that Scott continued to take initiative in expanding TokyoDev. Scott was one of our first external contributors, writing about his experience living with a disability in Japan. He encouraged me to expand and refine both our editing and submission processes so that we could reach out to even more contributors and platform their perspectives. The editorial team now consists of him and Rebecca Callahan, and they’ve had a hand in every article that TokyoDev has published. In other words, since 2022, Scott has shown that he cares about TokyoDev as much as I do. He is invested in what we do and why we do it, and shares my vision for what TokyoDev can become. What changes now Scott’s experiences as an engineer, a mentor, and a leader make me confident that, as our Head of Operations, he will continue to help TokyoDev mature. A big part of what has made TokyoDev successful is that I see the software developers who use our site as my peers and genuinely want to help them. Scott shares that perspective, and will join me in ensuring that TokyoDev remains true to its principles while we grow. So what changes in the short term? Nothing dramatic. I will teach Scott about managing TokyoDev as a business, and he will document our processes and products as a part of that learning. He will also look for areas of improvement while ensuring that we remain compliant with regulations and labor law. Over time, I will hand over some other responsibilities. I will continue to run TokyoDev, but TokyoDev will become less dependent on me for its day-to-day operations. Long term, I’m excited about what this will enable us to do. TokyoDev has always been about helping international software developers build successful careers in Japan, and bringing Scott on full time puts us in a much better position to continue doing that. We look forward to writing the next chapter of TokyoDev together.

18 hours ago • 1 votes
Speeding up Kidz Fun Art & making Google love it

Kidz Fun Art is a drawing, colouring and animation app for kids that I’ve been building since 2021. It runs in the browser also as a simple wrapper app on iOS, iPadOS and Windows. It wasn’t getting a great click through rate on Google, even for people who directly searched for it. So, for two days I took a hard look at how fast it loads and how search engines see it. It wasn’t flattering. This post covers what I found, what I changed and what the graphs say now. Short version: on a simulated slow phone, the homepage’s Largest Contentful Paint got about 2.6× faster (15.9 s to 6.1 s) and its first load is about 82% smaller (4.2 MB to 0.75 MB). I also fixed a set of SEO mistakes that are, frankly, embarrassing to write down. I’ll write them down anyway. Part 1: Google had no idea what the site was for I started by reading 16 months of Google Search Console data. 9,380 clicks in total. About 9,200 came from people who had typed “kidz fun art” or a close spelling. People searching for what the app actually does (“coloring app for kids”, “ai art for kids”, “make a comic book”) sent the site 164 clicks. In 16 months. Total. When there was a relevant page, Google ranked it well. The site was #1 for things like “drawing app for kids ipad” and a German query that means “paint by numbers app without ads”. There just weren’t many relevant pages. Then I looked at the code, and the cause was obvious. The homepage <title> was “Kidz Fun Art” in all 12 languages. That’s a fine name, and a terrible title. It tells a search engine nothing. The homepage’s first <h1> was the pricing table’s “Choose your experience”. I was, in effect, telling Google that the most important thing on my homepage was the checkout. Every blog post had the same meta description: a generic line about “news, updates, tips”. Each post’s front matter already had a perfectly good excerpt field that nobody read. Blog posts had two <h1>s: the site header and the post title. There was no structured data at all. The sitemap that redirected every single URL This one stings. The sitemap is the one file whose whole job is to say “here are my URLs, please index them”. Mine listed 17 URLs, and every one of them redirected. The sitemap build used an environment variable that resolved to kidzfun.art. The site lives on www.kidzfun.art, so every URL got a 308. Only the English blog posts were listed. The other 11 languages appeared only as hreflang alternates, which pointed at redirecting URLs too. There were no <link rel="canonical"> tags on any page and no hreflang in the page <head>. Google was left to guess which URL was the real one, and it guessed wrong a lot. What I changed: The sitemap is now built on https://www.kidzfun.art, with 204 URLs: every home page, blog index, blog post, About page and gallery page, in all 12 languages. Each one lists all of its language alternates plus an x-default. A shared SeoLinks component adds an absolute canonical (www, no query string) and the full hreflang set to every public page. The ?v= cache-busting URLs that had been showing up as duplicates now canonicalise to the clean URL. /xx/blog/yy/... URLs, which returned a 500 in production (oops), now 308 to /blog/yy/.... Login, account, debug, export and embed pages send X-Robots-Tag: noindex, follow from next.config.js, so they stop using up crawl budget. robots.txt now mentions the sitemap. Novel idea. Why Google skipped half the site Search Console’s Pages report had 93 of 174 known pages not indexed. Every reason on that list traces back to the mistakes above: “Page with redirect” (22): that sitemap, plus internal links to the non-www host. “Duplicate without user-selected canonical” (18): I hadn’t selected any canonicals. Fair cop. “Crawled, currently not indexed” (39): mostly translated posts that Google reached through redirecting URLs, plus thin pages like /login. “Discovered, currently not indexed” (12): Google found these and decided they weren’t worth a visit. With no sitemap entry and no hreflang, I hadn’t given it a reason to. On-page fixes Titles and descriptions: Each blog post got its own seoTitle and description, in all 12 languages. The meta description now comes from the post’s excerpt, which is what that field was for all along. The About pages take their title and description from their own localized Markdown. They had been sharing an English title and a generic description. One <h1> per page: A # heading inside a post’s Markdown now renders as an <h2>, so the post title is the only <h1>. The About page opts back in with a keepH1 prop. Its Markdown heading is the page title. This fix arrived in two parts. The first part left the About page with zero <h1>s. I noticed, eventually. Structured data and social tags: JSON-LD for the home page (the app), blog posts (articles) and the embedded videos. Open Graph and X/Twitter tags on every public page, so shared links get a proper card. A real 404 for deleted gallery images: The AI gallery shows a friendly “AI Artwork Not Found” page when an image has been deleted. It used to return 200 OK, which Google calls a “soft 404” and dislikes. It now returns a 404 with noindex, and a 503 if the Firestore lookup itself fails, so a database hiccup tells crawlers “come back later” rather than “this is gone”. Part 2: Making the homepage fast The homepage is the app. It works offline, so every dialog (save, stickers, colouring pages, “get an adult”, “no wifi”) is server-rendered into the HTML up front. That’s a deliberate trade-off, and I kept it because I want new users to be able to immediately be able to start drawing as soon as they launch the app. What I hadn’t thought about was what it meant for the network. What the homepage downloaded before the app could start I measured the live site with a Lighthouse-style mobile profile: slow 4G (1.6 Mbps, 150 ms latency), 4× CPU slowdown, empty cache. First load: 4.5 MB over 198 requests. The homepage HTML alone was 358 KB, with about 77 <img> tags in hidden dialogs. The browser dutifully fetched every one of those images. The script that starts the app (main.min.js, 191 KB) sat at the very end of the document, so the browser found it last and gave it whatever bandwidth was left. The app script finished arriving at about 14 seconds. The CPU was not the problem. Every long task was under 300 ms. This was purely about bandwidth and request order. I had built a very polite queue and put my own app at the back of it. Watch the queue The waterfall is a simplified illustration. The milestone times (first paint, LCP, load) are measured: slow 4G + 4× CPU, local production build, median of 3 runs. My Largest Contentful Paint was the “Contact support” link The canvas doesn’t count toward LCP, and the toolbar buttons are small. So on a slow load the largest thing painted was… the loading dialog. The loading dialog fades in its “Taking a while? Contact support” text after 5 to 7.5 seconds. On a slow connection, that text became the page’s LCP element, at 15.9 s. I was measuring my page speed by how long it took to suggest the user complain about my page speed. There’s a lesson in there somewhere. The fix wasn’t to change the dialog. It was to make the app start sooner, so it paints before that text ever appears. What I changed Preload the app script. I added <link rel="preload" as="script"> in <head> for main.min.js and errorHandler.min.js. The <script> tags stay where they were, so execution order doesn’t change. The browser just starts fetching them before any image. This one line did more than anything else on this list. It’s a little humbling. Turn the three dialog GIFs into MP4s. Three animated GIFs: an arrow pushing pictures into a tablet (927 KB), a dancing rainbow pencil (650 KB) and a paper plane (305 KB). That’s 1.9 MB of decoration in dialogs most visitors never open on their first visit. I re-encoded them with ffmpeg: H.264 High profile, -preset veryslow -crf 20, yuv420p, +faststart, constant frame rate taken from each GIF’s frame delay. The commands are committed as scripts/gif-to-mp4.sh. The result is 130 KB in total, with SSIM between 0.988 and 0.993 against the originals. The pencil needed tpad=stop_mode=clone:stop_duration=0.2, because ffmpeg’s GIF reader drops the final 250 ms hold and the dance lost its big finish. The new <video autoplay loop muted playsinline> tags render at exactly the same size and class as the old <img> tags. Alt text moved to aria-label. Locked colouring thumbnails were full-size PNGs. In the colouring page picker, locked pages used the full-size colouring PNG as their background image, inlined into the HTML. That came to about 1.3 MB on every first visit, to draw thumbnails in a dialog that was closed. They now use the small image, set when the picker opens, like the unlocked ones always did. Sticker thumbnails wait their turn. I tried loading="lazy" first. It didn’t help: Chrome fetched the images before the stylesheet that hides the dialogs had arrived, so as far as it knew they were visible. Sticker thumbnails and the media library’s YouTube thumbnail now use data-deferred-src. They load 3 seconds after the load event, or as soon as their dialog opens, whichever comes first. The service worker preload starts after load. The offline preload queue (about 2 MB of colouring pages and stickers) used to start while the page was still loading and compete with it. Now it starts after the load event. Same files, same offline result, no fighting for bandwidth. Analytics is async. Nothing waited for it, so nothing needed to block on it. Cache headers. /images/*: max-age=86400, stale-while-revalidate=604800. It had been max-age=0, so every image was re-checked on every visit. Versioned /js, /css and /addToHomescreen files are immutable for a year in production. Offline still has to work Offline support is a core feature, so “just don’t download it” was never an option. Some of the changes above put it at risk, and a couple of things turned up along the way: Safari plays video from byte ranges. Safari requests video with Range: bytes=.... Answer that with a full cached response and the video won’t play. The service worker now answers Range requests from its cache with a proper 206 Partial Content slice (lib/util/rangeResponse.ts, with unit tests). First-visit gap: on a first visit the service worker isn’t controlling the page yet, so dialog images only reached the offline cache on the second online visit. The page’s own dialog images and videos now go to the front of the offline preload queue on the first visit. I nearly downloaded my whole site, 12 times over. The service worker cached every <link href> it found in the page. The new SEO work had just added canonical and hreflang <link>s pointing at all 12 localized homepages. So every new visitor would have downloaded about 12 extra homepages, in languages they don’t speak, “for offline use”. I caught it before production. The service worker now skips rel=canonical and rel=alternate. Safari stopped the service worker mid-download. The old preload queue ran on timers after the request had been answered. Safari considers an idle service worker fair game, so it stopped it after the first few images. The page now sends images in batches of 10, and the service worker caches each batch before it replies. A page lock-up I’d never noticed. resizeDialog added a new “image loaded” listener every time the window resized. With lots of images loading at once, the listeners multiplied until the page locked up. It now attaches one listener per image, which, in hindsight, is how many it needed. Part 3: The blog Blog index cards used the full 1920 px screenshots as covers, up to 500 KB each, in a box about 200 px wide. Each card was a little billboard, shrunk down by the browser on every visit. Covers now go through next/image with sizes that match the actual card widths, so the browser gets a resized WebP. The first few cards get priority. The rest load lazily. The first sizes hint was too small at some widths and made covers blurry. It now matches the real card widths, up to about 630 px between 769 px and 1028 px wide. Post pages: The cover image gets fetchpriority="high", and images further down the post load lazily. Five images were recompressed in place, keeping the same filenames and dimensions. The PNGs came out about 4× smaller and the JPEGs about 40% smaller. I deleted a 1.1 MB cover.png that nothing referenced. All 12 translations of that post used cover.jpg. The PNG had just been sitting in public/ taking up space. Results on the slow 4G profile: /blog LCP went from 13.3 s to 1.8 s. A typical post went from 3.9 s to 1.7 s. The gallery didn’t get faster, on purpose. It got a 5-minute edge cache and a cached Firestore image count, which fixed its slow server responses. I decided not to change its 20 full-size PNG thumbnails, so its lab LCP barely moved (8.4 s to 8.6 s). That’s a choice, and the chart owns it. Part 4: Lighthouse homework After the speed work went live I ran Lighthouse on the production homepage (mobile) and cleaned up what it flagged. Performance stayed in the low 70s, so I have some more work to do, but it’s moved nicely in the right direction. Part 5: Telling the search engines Fixing the site is half the job. The other half is getting crawlers to come back and notice. Google Search Console: Resubmitted the www sitemap. Clicked “Validate fix” on “Duplicate without user-selected canonical” and on the redirect errors. Requested indexing for the main language homepages and the top blog posts. The quota is about 10 a day, so it’ll take a few days. Wrote down a baseline from the Performance report, so in 4 to 8 weeks I can tell whether any of this worked. Bing Webmaster Tools: Submitted all 204 sitemap URLs through URL Submission. The daily quota is 10,000, so no trickle-feeding needed. Bing’s index also feeds DuckDuckGo and several AI search tools, so it’s cheap extra reach. Most of Bing’s “SEO recommendations” pointed at old ?v= URLs and old titles. They’ll clear as Bing recrawls. What I’m not watching: the Lighthouse score. Google ranks on real-user Chrome data (the Chrome UX Report): a rolling 28-day window, judged at the 75th percentile. So the honest answer to “did it work?” is “ask me in a month”. How I kept from breaking things The app has hundreds of unit and integration tests, all of which still pass (even though they do take over 30 minutes to run). I also manually regression tested all the riskiest changes. Hopefully I don’t make things worse before they get better… Lessons, mostly at my own expense Read your own sitemap. Actually open it and click a URL. Mine had been quietly redirecting for who knows how long. <link rel="preload"> for the script that boots your app is the cheapest big win there is. Browsers fetch resources in the order they find them. If your app script is at the bottom of a 358 KB document full of images, it really is last in line. Check what your LCP element actually is before you try to make it faster. Mine was a “Contact support” link. GIF is an image format from 1987 that I was using as a video format. A real video codec beats it by an order of magnitude at the same quality. try/catch doesn’t catch promise rejections. I knew that. My code didn’t. Every <link> you add to <head> is something your service worker might decide to download. Speed scores are for diagnosis. Rankings come from real users. Fix what the lab finds, then wait for the field data. Epilogue You’re still here? Wow. Cool. After all this, I’m hoping that users notice nothing other than quicker app start times. I’m looking forward to keeping an eye on traffic and retention in the coming weeks. Wish me luck!

20 hours ago • 1 votes
Why we're moving our warehouse off DuckDB

Five months ago, we rebuilt our warehouse on DuckDB instead of ClickHouse. We did it because a shared ClickHouse cluster couldn't handle hours-long…

20 hours ago • 1 votes
Archives on custom domains unreachable

Our public postmortem for the incident on October 20th, 2026.

20 hours ago • 1 votes
📚 BoredReading

You seem to be enjoying this.

Join free to unlock everything.

Create free account

Already have an account? Sign in