![\"A](\"https://blog.andrewbran.ch/img/rpA_KDxObd-2052.webp)
Time for another Tweet analysis:
\n\n\n\n\nBrandon McConnell
\n
\n@branmcconnellApparently, I've been doing NPM package exports in TSC wrong my entire life. I usually use the ESM
\nexport default _if I'm doing a default export.This generated CJS output appears to break when require'd in a CJS environment, requiring a property ref of
\npackageName.defaultinstead of simplypackageName.After much research, it appears the generally recommended fix is to use
\nmodule.exports =in your main ESM file that TSC processes. WHAT. That's not a typo.You can use any ESM imports or syntax you need in that file, but for the CJS output file to use
\nmodule.exports, the ESM needs to use it too. Why can't TSC convertexport defaulttomodule.exports =for the CJS target?Doing this also appears to mess with the export types, so the
\n.d.tsfiles sometimes get emptied out unless you export your exports with both ESM and CJS syntax together, even like this:\nexport default myFunction;\nmodule.exports = myFunction;\nHas anyone else run into this? Twilight Zone moment with a simple fix? đ€đŒ
\n\n10:30 AM · Nov 14, 2023\n\n
This is a great breakdown bringing up some interesting points. Everything in it is factually correct, but the âfixâ Brandon heard recommended is wrong. Letâs get into the details.
\nA CommonJS module can export any single value by assigning to module.exports:
module.exports = \"Hello, world\";\nOther CommonJS modules can access that value as the result of a require call of that module:
const greetings = require(\"./greetings.cjs\");\nconsole.log(greetings); // \"Hello, world\"\nmodule.exports is initialized to an empty object, and a free variable exports points to that same object. Itâs common to simulate named exports by mutating that object with property assignments:
exports.message = \"Hello, world\";\nexports.sayHello = name => console.log(`Hello, ${name}`);\nconst greetings = require(\"./greetings.cjs\");\nconsole.log(greetings.message); // \"Hello, world\";\ngreetings.sayHello(\"Andrew\"); // \"Hello, Andrew\";\nECMAScript modules are fundamentally different from CommonJS modules. Where CommonJS modules expose exactly one nameless value of any type, ES modules always expose a Module Namespace Objectâa collection of named exports. This creates something of a paradox for translating between module systems. If you have an existing CommonJS module that exports a string:
\nmodule.exports = \"Hello, world\";\nand you want to translate it to ESM, then transform it back to equivalent CommonJS output, what input can you write? The only plausible answer is to use a default export:
\nexport default \"Hello, world\";\nBut if you ever add another named export to this module:
\nexport default \"Hello, world\";\nexport const anotherExport = \"uh oh\";\nyou now have a problem. The transformed output canât be
\nmodule.exports = \"Hello, world\";\nmodule.exports.anotherExport = \"uh oh\";\nbecause attempting to assign the property anotherExport on a primitive wonât do anything useful. Remembering that default exports are actually just named exports with special syntax, youâd probably conclude that the output has to be:
exports.default = \"Hello, world\";\nexports.anotherExport = \"uh oh\";\nSo does an export default become module.exports or module.exports.default? Should it really flip flop between them based on whether there are other named exports? Unfortunately, different compilers have landed on different answers to this question over the years. tsc took the approach of always assigning ESM default exports to exports.default. So export default "Hello, world" becomes:
Object.defineProperty(exports, \"__esModule\", { value: true });\nexports.default = \"Hello, world\";\n(The __esModule marker, an ecosystem standard that first appeared in Traceur, is used by transformed default imports, but isnât relevant for the rest of this post. A more complete discussion of ESM/CJS transforms and interoperability can be found in the TypeScript modules documentation.)
This answers one of the questions posed in the tweet:
\n\n\nWhy can't TSC convert
\nexport defaulttomodule.exports =for the CJS target?
Thereâs an argument for doing thatâsome compilers do, or expose options to do thatâbut every approach has tradeoffs, and tsc chose a lane extremely early in the life of ESM and stuck with it.
export default aloneWith that background, it should be easy to interpret the behavior Brandon observed:
\n\n\nI usually use the ESM
\nexport default _if I'm doing a default export... This generated CJS output appears to break when require'd in a CJS environment, requiring a property ref ofpackageName.defaultinstead of simplypackageName.
export default _ turns into exports.default = _, so if someone writing a require wants to access _, of course they need to write a property access like require("pkg").default to get it.
This is only a âbreakâ if you have a specific expectation about how to translate from ESM to CJS, and as I argued in the previous section, all such expectations are fraught with inconsistencies and incompatibilities. The ESM specification didnât say anything about interoperability with CommonJS, so tools that wanted to support both module formats kind of just made it up as they went. This is not to say that the outcome was good or even that tscâs decision to always assign to exports.default looks like the best decision with the benefit of nine years of hindsight. It wasnât mentioned in the tweet, but the exports.default output is also problematic when imported by true ES modules in Node.js:
// node_modules/hello/index.js\nObject.defineProperty(exports, \"__esModule\", { value: true });\nexports.default = \"Hello, world\";\n\n// main.mjs\nimport hello from \"hello\";\nconsole.log(hello); // { default: \"Hello, world\" }\nconsole.log(hello.default); // \"Hello, world\"\nOur real default import fails to bind to our transformed default exportâwe still need to access the .default property! This can make it nearly impossible to write code that works both in Node.js and in all bundlers. So, while the behavior with transformed export default in tsc is understandable and predictable, it is indeed problematic for libraries.
module.exports = to the inputApparently, there is some conventional wisdom floating around that the way to solve this problem is to add a module.exports = assignment to the TypeScript module, along with the export default statement. This is a Bad Idea, and Brandon included a clue as to why:
\n\nDoing this also appears to mess with the export types, so the
\n.d.tsfiles sometimes get emptied out unless you export your exports with both ESM and CJS syntax together, even like this:\nexport default myFunction;\nmodule.exports = myFunction;\n
The key is that TypeScript doesnât understand module.exports in TypeScript files, so it passes that expression through verbatim to the output JavaScript file, while emitting nothing for it into the output .d.ts file. Thatâs why writing module.exports without export default emits an empty declaration file. Including them both, the resulting output files look like:
// myFunction.js\n\"use strict\";\nObject.defineProperty(exports, \"__esModule\", { value: true });\nfunction myFunction() { /* ... */ }\nexports.default = myFunction;\nmodule.exports = myFunction;\n// myFunction.d.ts\ndeclare function myFunction(): void;\nexport default myFunction;\nIn the JavaScript, the module.exports = myFunction completely overwrites the effect of exports.default = myFunction. But the compiler doesnât know that; all it sees (from a type perspective) is the default export, so thatâs what it includes in the declaration file. So the JavaScript and TypeScript are out of sync: the types assert that the shape of the module is { default: () => void }, when in reality, itâs () => void. If a JavaScript user were to require this module, IntelliSense would guide them to write:
require(\"pkg/myFunction\").default();\nwhen they actually need to write
\nrequire(\"pkg/myFunction\")();\nđ„
\nThe idea that the output JavaScript should use module.exports = instead of exports.default = is a good one; we just need to accomplish that in a way TypeScript understands, so the JavaScript and declaration output stay in sync with each other. Fortunately, there is a TypeScript-specific syntax for module.exports =:
function myFunction() { /* ... */ }\nexport default myFunction; \nexport = myFunction; \nThis creates the output pair:
\n// myFunction.js\n\"use strict\";\nfunction myFunction() { /* ... */ }\nmodule.exports = myFunction;\n// myFunction.d.ts\ndeclare function myFunction(): void;\nexport = myFunction;\nThe JavaScript uses module.exports and the types agree. Success!
One inconvenience to this approach is that youâre not allowed to include other top-level named exports alongside the export =:
export interface MyFunctionOptions { /* ... */ }\nexport = myFunction;\n// ^^^^^^^^^^^^^^^^\n// ts2309: An export assignment cannot be used in a module with\n// other exported elements.\nDoing this requires a somewhat unintuitive workaround:
\nfunction myFunction() { /* ... */ }\nnamespace myFunction {\n export interface MyFunctionOptions { /* ... */ }\n}\nexport = myFunction;\nDefault exports, even transformed to CommonJS, are not a problem as long as the only person importing them is you, within an app where all your files are written in ESM syntax and compiled with the same compiler with an internally consistent set of transformations. Tools to compile ESM to CommonJS started emerging in 2014, before the specification was even finalized. Iâm not sure anyone thought very hard about the possible long-term consequences of pushing a huge amount of ESM-transformed-to-CommonJS code to the npm registry.
\nTypeScript library authors are now encouraged to compile with the verbatimModuleSyntax option, which prevents writing ESM syntax when generating CommonJS output (i.e., the compiler forces you to use export = instead of export default), completely sidestepping this compatibility confusion.
I see two reasons to be hopeful for the future.
\nTypeScript 5.5, just released in beta, introduces an --isolatedDeclarations option, which lays the groundwork for third-party tools to implement their own fast, syntax-based declaration emit. I mentioned earlier that some existing third-party tools have options that solve this problem for JavaScript emit, but donât generate declaration files, potentially creating a worse problem. Hopefully, the next generation of JavaScript and TypeScript tooling will generate declaration files that accurately represent the transformations they do to generate their JavaScript output.
Secondly, Node.js v22 includes experimental support for being able to require ESM graphs. If that feature lands unflagged in the future, there will be much less of a reason for library authors to continue shipping CommonJS to npm.
I started to reply to this tweet, but I think it deserves more than a hasty string of 240-character concatenations:
\n\n\n\n\nMatt Pocock
\n
\n@mattpocockukcc @atcb in case I've got something drastically wrong.
\nSummary:
\nI think that if you transpile TS code with
\nNodeNext, that will be compatible with any modern bundler (anymoduleResolution: Bundlerenvironment).@tpillard thinks that there are issues which mean you should transpile one export with
\n\n10:30 AM · Nov 14, 2023\n\nmoduleResolution: Bundlerand another withmoduleResolution: NodeNextif you plan to support both.
I mostly agree with Matt, and his advice earlier in the thread more or less matches what I published in TypeScriptâs Choosing Compiler Options guide for modules.
\nItâs worth unpacking some of the nuances here. Something important about Timâs position, and about how tsc works, is lost to the Twitter shorthand in Mattâs characterization above. moduleResolution doesnât affect tscâs emit, so producing two different outputs toggling that option alone would do nothing for consumers. But as Matt and Tim both know, itâs not possible to toggle just moduleResolution between bundler and nodenext, because each of these enforces a corresponding module option, which does affect emit:
moduleResolution: bundler requires module: esnextmoduleResolution: nodenext requires module: nodenextSo at face value, the real question posed in Mattâs tweet is whether there are differences in emit between module: esnext and module: nodenext that might cause bundlers to trip over nodenext code.
The most important thing to understand about module: nodenext is it doesnât just emit ESM; it emits whatever format it has to in order for Node.js not to crash; each output filename is inherently either ESM or CommonJS according to Node.jsâs rules and tsc chooses its emit format for each file based on those rules. So depending on the context, we might be asking be asking about the difference between CommonJS and ESM, or the difference between module: esnext and the particular flavor of ESM produced by module: nodenext.
Bundlers are capable of processing (and typically willing to process) both CommonJS and ESM constructs wherever they appear (unlike Node.js, which parses ES modules and CommonJS scripts differently), so itâs fair to say that the potential difference in module format between module: esnext and module: nodenext will not itself break bundlers (although most bundlers have more difficulty tree-shaking CommonJS than ESM).
There is, however, one specifically Node.js-flavored emit construct that could derail a bundler. In module: nodenext, a TypeScript import/require inside an ESM-format file:
// @Filename: index.mts\nimport fs = require(\"dep\");\nhas a special Node.js-specific emit:
\n// @Filename: index.mjs\nimport { createRequire as _createRequire } from \"module\";\nconst __require = _createRequire(import.meta.url);\nconst fs = __require(\"dep\");\nI assume this wonât work in most bundlers, though some have built-in Node.js shims, so I could be proven wrong. But this is a clear case where module: nodenext would allow Node.js-specific code to be emitted; itâs just not something someone is likely to write by mistake.
Continuing import/require shows another way to frame the question. Suppose we had our input code:
// @Filename: index.mts\nimport fs = require(\"dep\");\nand in order to avoid the potential for Node.js-specific emit to crash a userâs bundler, we decided to produce two outputsâone for Node.js and one for bundlers. When switching to module: esnext and moduleResolution: bundler, our input code errors:
\nts1202: Import assignment cannot be used when targeting ECMAScript modules. Consider using 'import * as ns from \"dep\"', 'import {a} from \"dep\"', 'import d from \"dep\"', or another module format instead.\nSo the question isnât fully answered just by looking at the transforms applied by these module modes; we also need to ask whether valid input code in module: nodenext is also valid in module: esnext and moduleResolution: bundler. If there are compilation errors, thatâs a strong signal that the output code will be a problem.
Beyond this one emit incompatibility, what other compilation errors are possible? Earlier in the Twitter thread, the theory was that module resolution is the problem. Letâs define exactly what that would mean. Imagine we have an output file like:
\n// @Filename: utils.mjs\nimport { sayHello } from \"greetings\";\nsayHello([\"Matt\", \"Tim\"]);\nSuppose we generated this file from a TypeScript input that compiled error-free under module: nodenext, meaning that TypeScript did its best to model how Node.js will resolve the specifier "greetings", found type declarations for the resolved module, and verified that the usage of the API was correct. The theory that this analysis does not provide a similar level of confidence that this code will work in a bundler due to module resolution differences presupposes that at least one of these outcomes is possible:
"greetings""greetings" to a module that has a sufficiently different shape, such that, if the types for that module were known, TypeScript would report an error for the usage of the APIThese are both absolutely possible via conditional package.json "exports". For example, "greetings" could define "exports" like:
{\n\t\"exports\": {\n\t\t\"module\": \"./contains-only-say-goodbye.js\",\n\t\t\"node\": \"./contains-only-say-hello.js\"\n\t}\n}\nThis would direct bundlers to one module and Node.js to another, each having a completely different API. In this case, it would be impossible to write a single import declaration that works in both contexts, and TypeScript could be used to catch an error like this by type checking the input code under multiple module/moduleResolution/customConditions settings. But this is terrible, terrible practice! I donât think Iâve ever seen this in a real npm package (and I have looked at a lot of package.jsons in the last year).
Indeed, the only difference between moduleResolution: bundler and the CommonJS moduleResolution: nodenext algorithm in TypeScript is import conditions, and every resolution that can be made in the ESM moduleResolution: nodenext algorithm will be made the same way in moduleResolution: bundler, with the exception of where import conditions cause them to diverge. (If there are other differences in the real resolution algorithms of bundlers and Node.js, they are not reflected in TypeScriptâs algorithm, so additional checking with TypeScript wonât help.) Keep in mind that bundlers came about in large part so that modules on npm, written under the assumption that only Node.js would be able to use them, could be used in the browser, which lacked a module system at the time. Bundlers would not be doing their job if their module resolution algorithms choked on Node.js code. Conditional exports can be used to redirect a bundler, but doing this in a way that breaks the contract of the module that Node.js would see is arguably a bug.
In other words, module resolution is not an issue unless a package is doing something extra terrible with "exports".
The last possible incompatibility (that TypeScript can catch) is how modules of different formats interoperate with each other. Iâve written about this extensively elsewhere, so suffice it to say that it is possible to have a default import:
\nimport sayHello from \"greetings\";\nthat must be called one way in a bundler:
\nsayHello();\nand another, unintentionally different way in Node.js:
\nsayHello.default();\neven though both module systems resolved to the same module. If you are writing a library, compiling to ESM, checking with module: nodenext, and find yourself needing to write .default() on something you default-imported, there is a possibility that your output code will not work in a bundler. (There is also a possibility that the type declarations for the library are incorrectly telling TypeScript that .default is needed, when in fact it is either not needed or not present!)
Mattâs advice, my usual advice, and the TypeScript documentationâs advice is that youâre usually basically fine to use nodenext for all libraries:
\n\nChoosing compilation settings as a library author is a fundamentally different process from choosing settings as an app author. When writing an app, settings are chosen that reflect the runtime environment or bundlerâtypically a single entity with known behavior. When writing a library, you would ideally check your code under all possible library consumer compilation settings. Since this is impractical, you can instead use the strictest possible settings, since satisfying those tends to satisfy all others.
\n
But Tim is right that this is imperfect. Itâs definitely possible to construct examples that break. In reality, breaks only occur in the face of packages that are behaving badly. (Unfortunately, a fair number of packages behave badly.)
\nI think I would summarize as:
\nnodenext is the right option for authoring libraries, because it prevents you from emitting ESM with module specifiers that only work in bundlers but will crash in Node.js. When writing conventional code, using common sense, and relying on high-quality dependencies, its output is usually highly compatible with bundlers and other runtimes.tsc --noEmit under different module/moduleResolution options.When I first created this blog in 2019, its inaugural post was titled Overengineering a Blog, which is precisely what I did. I wanted every code block to be a tiny TypeScript playground of sorts. Unsurprisingly, this was a huge pain to maintain, and I lost interest not only in using the interactive features I worked so hard to create but also in writing altogether. I put a colossal amount of effort into a few of the early posts, which made me hesitant to publish anything less polished. Shifting to working from home during COVID brought about a general technology fatigue during which I couldnât imagine thinking about TypeScript or even being on a computer outside of work hours. The combination of these factors led to the three-and-a-half-year hiatus in posts preceding this one.
\nIn considering relaunching the blog and beginning to write again, I didnât just want to make the infrastructure easier to maintain; I also wanted to give myself permission to publish posts that donât take so much work that I burn out on writing for years afterward. Years ago, I was hoping to write mostly opinionated educational content, so I was highly concerned with correctness and credibility, and only dared to write about topics on which I thought I could present as an expert. Now, thereâs only one topic I can plausibly claim to be an expert on, so I donât plan to write a lot of posts with the aim of convincing anyone to do anything. I feel more comfortable now with simply presenting information I find interesting, which makes it much easier to publish.
\nI was tempted to redesign everything, but in the spirit of trying to actually write again instead of spending forever just working on the site, decided not to. I made a few small changes that Iâm really happy with:
\nAfter making these changes, I found I was still quite happy with the design. A part of me wanted to switch to a humanist sans-serif body font for technical posts, which I expect to make up the majority of future posts, but I couldnât give up Heldane for prose. I may experiment with using different typefaces for posts of different categories, but this is fine for now.
\nThe old blog was built with Gatsby. Since I decided to remove all the interactive components, there was no longer any reason to use React (or to have any client-side JavaScript at all) as part of the site generator. (I was not opposed to using React/JSX as my templating language, but without the need to hydrate any statically rendered components, it was not a necessity.) I considered Hugo for its unmatched speed, but decided that Eleventy would be faster for me to configure and customize since I know JavaScript about a million times better than I know Go.
\nFor styling, the old blog used Emotion and Typography.js, which I actually liked quite a bit, but didnât make sense to use without React or JavaScript. I ported my typography styles to plain CSS and used Tailwind via UnoCSS for the layout.
\nI also decided to drop Google Analytics. I donât look at the metrics, and donât want to be complicit in any privacy harm it may be doing. I might try to self-host a more privacy-focused analytics platform in the future, but Iâm ok not knowing anything about the traffic for now.
\nlink tags pointing to those generated URLs. More than good enough without taking a dependency on a full bundler..d.ts) for Eleventy configuration and plugins were almost universally incorrect, an incomplete afterthought, or completely absent. Writing any amount of JavaScript that interacts with the generator is a really poor experience for those who are accustomed to being able to rely on IntelliSense (which feels like, pretty much everyone using any modern JS tools now?).theme.breakpoints is just a renaming of Tailwindâs theme.screens, while seemingly every other theme option keeps the same name?), and I really missed Tailwindâs excellent VS Code extension. UnoCSS has a VS Code extension too, but it doesnât activate on Liquid templates, and seemed not to be reading my customizations from my config file (perhaps because I named it uno.config.mjs instead of uno.config.js?). All it did was underline every occurrence of the word âmyâ in my Markdown files. After discovering the extension has no documentation whatsoever that I could use to attempt to debug these problems, I uninstalled it.I recently outlined a post detailing the history and design considerations of type-only imports, a TypeScript feature I worked on. I think that will be interesting for, you know, a very niche audience, but it would benefit from being able to lean on a separate technical explainer of TypeScript declarations and symbols, which is something I wish someone had already written when I was learning the compiler API. So I plan to start working on those two soon.
\n", "date_published": "2023-11-12T00:00:00Z" } , { "id": "https://blog.andrewbran.ch/marketing-web-rules/", "url": "https://blog.andrewbran.ch/marketing-web-rules/", "title": "Marketing Web Rules", "content_html": "In early 2016, I was working as a web developer on the marketing team at Xamarin. We had just built the event site for the third Xamarin Evolve, the companyâs developer conference, to be held in Orlando in the spring. The event afforded an opportunity to our designers to push the Xamarin brand and palette into more adventurous territory, so the site materialized at a larger-than-life scale, with massive all-caps headings, hundreds of pixels between sections, and neon SVG animations, all set atop a vertical gradient background rotating through every color of a Florida sunset.
\nMy teammates and I also used it as an opportunity to try out some newer tech than what we had inherited in the monolithic .NET company site. React, Webpack, and CSS modules were becoming dominant forces in the frontend web world, and we were excited to bring a modern toolset into into our daily work. The result was infrastructural overkill, but it was also rapid iteration and developer happiness.
\nIn April, less than a month before the conference, we received two independent bug reports that the registration buttonâthe single most important link on the siteâwas missing on mobile Safari. When we couldnât reproduce the bug on our own devices or on any iOS simulator device, it was difficult to determine next stepsâitâs tough to fix a bug you canât observe. Eventually, after broadcasting a plea across the company Slack, we found a coworker whose iPhone exhibited the bug, and my teammate, Clay, determined that the content blocker Purify was hiding the button.
\nBut⊠why? The content blocker wasnât using any suspicious custom configuration; it was just supposed to block ads. What was unique about the registration button, when other buttons on the site were displaying correctly? Plugging the phone into a Mac and inspecting the button with Safariâs developer tools eliminated the guesswork. Purify was injecting a large number of CSS rules into the page, including this one:
\n[class$=\"Ad\"] {\n\tdisplay: none;\n}\nThat attribute selector syntax means hide everything with a class name ending in âAd.â [1]
\nAnd sure enough, that applied to our button. We didnât author a class ending in âAdâ; rather, we were having Webpack append a base64 content hash to the end of each selector to guarantee uniqueness across CSS files and prevent naming collisions, as is the common practice with CSS modules:
\nlocalIdentName=[name]__[local]___[hash:base64:5]\nThis meant that for a class name register-button in a file styles.css, the emitted class name would be something like styles__register-button__fQ2Ad, where the five-character suffix is a hash of the file content and the original class nameâeffectively a random set of letters and numbers. And it just happened that after an innocuous update of other CSS in that file, the hash for the single most important element on the page changed to end in Ad.[2]
A wacky solution to a wacky problemâif you donât want a random string to end in Ad, make sure it ends in something else:
Clay appended the letter c to every generated class name. Problem solved.
Interacting with buggy websites is a near daily occurrence, and as a software engineer who, I like to think, generally did a good job with the material I created when I worked in web, I instinctively feel incredulous when I encounter glaring errors on high-traffic production sites. This login form had one job. Who did something dumb? When I think about our vanishing button, Iâm inclined to look more generously at mistakes that appear to reflect incompetency. The simplicity of the bugs we observe often belies the complexity of the systems that created them.
\nâ
\nA year later, I was writing the Webpack configuration for App Center with the same teammates who worked with me on the Evolve site, and recalling the Purify incident, I preemptively guarded our loader configuration against it. In the period after Xamarin was acquired by Microsoft, we were still officially on the Xamarin marketing team, but as Xamarin work was winding down, we were starting to spend much of our time helping App Center get off the ground. We had a sense of pride, I think, that we were working on rather fundamental pieces of infrastructure as a rag-tag band of outsiders from a marketing team. And so, with the atmosphere of team spirit and all the creative maturity of a nine-year-old, I chose to suffix the content hash with the letters mwr, a secret acronym for âMarketing Web rules.â It had a practical justification as well, I told myself, since choosing multiple letters that are phonetically incongruous and never appear at the end of any word, I supposed, would have even lower chances of triggering overzealous ad-blocking rules. I committed the configuration, and then completely forgot about it for the next three years, until starting to write this post.
In those intervening years, App Center has moved repositories twice, gone through at least two major version upgrades of Webpack, formed an official core frontend team, and turned over the majority of that original team, myself included. So there was no way our little easter egg survived all that churn, I thought. It must have been lost, or someone must have removed it after noticing it in the source, in the browser developer tools, or in all the times itâs come up in Slack when someone pastes a Webpack error message originating from css-loader.
\n![\"A](\"https://blog.andrewbran.ch/img/68x15pp-f--2618.webp)
![\"A](\"https://blog.andrewbran.ch/img/0otL5JTYqy-2618.webp)
Nope. To this day[3], the string mwr appears 167 times in the DOM on the login page alone. Woops. Iâm grateful for gzip.
It appears that Purify has since removed wildcard attribute selectors like this one. â©ïž
\nA little back-of-the-napkin math: assuming a hash algorithm with a perfectly uniform distribution, the odds of a base64 string having a particular N-character suffix is 1/64N. So, the chances of any one of our hashes ending in âAdâ was 1 in 4096. I had always assumed this event was a statistical anomaly, but given the number of CSS classes we generated (not just per-build, but over the course of dozens of updates where hashes were regenerated), it starts to look less surprising. â©ïž
\nBefore publishing this piece, I gave the App Center team a heads up, and they promptly shortened class names in production down to just an 8-character hash (plus the letter x, for good measure), citing a 1.4% reduction in post-compression asset weight on the login page. In non-production environments? Still mwr. đ â©ïž
When I joined the TypeScript team, debugging quickly became my most valuable skill, and by the same token, the debugability of the compiler became one of the codebaseâs most valuable assets. The TypeScript compiler is just a Node app so itâs pretty easy to debug, but Iâve found a few useful tricks specific to the TypeScript codebase. Thanks to a request over Twitter, here they are.
\nThe first section of this post is like a quick-start: Iâll get you a debug session running as quickly as possible. If youâre already somewhat familiar with the compiler, this might be all you need. But if you find yourself struggling to navigate that debug session or figure out what part of the code you want to debug, hang in there! The second section provides tips for finding strategic breakpoint locations and inspecting the compiler state while paused.
\nThe first step for any method of debugging is to clone and build TypeScript from source so we can step through the original TypeScript source instead of the bundled JavaScript files.
\ngit clone git@github.com:microsoft/TypeScript.git\ncd TypeScript\nnpm install\nnpm run build\nThe built compiler and source maps are now in built/local, including a file called tsc.js. Anywhere you would normally use tsc, you can now use node built/local/tsc.js. For example:
$ node --inspect-brk built/local/tsc.js -p ../MyBuggyProject\n\nDebugger listening on ws://127.0.0.1:9229/60b1b25a-f29d-4568-8619-b5e29b6dee25\nFor help, see: https://nodejs.org/en/docs/inspector\nNode is paused at the beginning of tsc.js and waiting for you to attach the debugger of your choice. Iâll be demonstrating use of VS Codeâs built-in debugger[1], but any Node debugger that can attach to a listening debug port will work.
\nIf you havenât already, open the TypeScript codebase in VS Code. Open the command palette and select âDebug: Attach to Node Process,â then select the process you just started (on port 9229 by default).
\n![\"A](\"https://blog.andrewbran.ch/img/QtVjOMjl2P-1592.webp)
VS Code will open tsc.js and show that the debugger is paused on the first line. From here, you can continue or step the debugger and hit breakpoints in the TypeScript source files.[2]
\nIf you need to debug a language service feature (like a refactor, a code fix, the formatter, or code completion), debugging VS Codeâs TS Server instance is often the most convenient approach. Again, youâll need the TypeScript codebase cloned, built, and opened in one VS Code window. Youâll also need another VS Code window opened to a project of your choice. (I have a dedicated project filled with nonsense TypeScript and JavaScript files for this purpose.) Weâll use the former VS Code window to debug the latter. (Impressively, a single VS Code instance can debug its own TS Server process, but TypeScript-powered editor features like go-to-definition donât work while the process is paused, so itâs much easier to use two windows.)
\nThe window you want to debug needs to be opened with the environment variable TSS_DEBUG set to a port number. If you have the code CLI tool, you can do this from the command line:
cd example-project\nTSS_DEBUG=9559 code .\nJanuary 2020 update: I recently published a VS Code extension that can restart an open windowâs TS Server process with a debug port listening. Could save you a step!
\nNext, you need to tell that VS Code window where to find the version of TypeScript that you built locally so it can be used for TS Server. Create or modify your example projectâs .vscode/settings.json file with the following setting:
{\n\t\"typescript.tsdk\": \"../path/to/TypeScript/built/local\"\n}\nNow, back in the window with the TypeScript codebase, open the command palette and select âDebug: Attach to Node Process,â then select the process running on the port you selected for TSS_DEBUG.
This time, youâre connected to a long-running process thatâs not paused. To pause on something useful, youâll need to set a breakpoint in an interesting function and trigger that function from your example project window. A good place to start is services.ts. As an example, to step through quick info generation, set a breakpoint in the function called getQuickInfoAtPosition, then in the example project window, hover a variable in a TypeScript or JavaScript file. The debugger in the other window should pause on that breakpoint.
![\"A](\"https://blog.andrewbran.ch/img/ZAQw7-bdzB-1224.gif)
The last method of debugging Iâll cover is perhaps the most expedient of all, especially if youâre working on actually contributing a bug fix or feature to the compiler. To do so, youâll of course want to write tests, and it turns out that debugging those tests is really easy.
\nAll the files in tests/cases/compiler and tests/cases/conformance are just snippets of TypeScript (or JavaScript) that the compiler runs against. You wonât find any assertions in them; instead, info about how the compiler runs on these snippets is saved to tests/baselines/reference, and the assertion is that future compilations always match the info saved there. (This is exactly the same concept as snapshot testing, which you might be familiar with in Jest.)
The TypeScript codebase includes a VS Code debugger configuration file for working with these files. To use it, simply copy .vscode/launch.template.json to .vscode/launch.json. Set breakpoints in the part of the compiler youâre interested in (Iâll cover some tips on how to find this shortly), then, open any test file in tests/cases/compiler or tests/cases/conformance (or tests/cases/fourslash, but those can be a bit trickier). Open VS Codeâs debug panel, and click the play button. After a few moments, you should hit your first breakpoint.
Now you know the mechanics of how to start debugging, but how do you debug productively? Stepping through every line of a typical TypeScript compiler run would take⊠tens of hours, perhaps? How do you determine the relevant parts?
\nThe answer is that it comes with time spent in the codebase, but having a high-level understanding of the organization of the compiler helps.
\nEarlier, we saw how to debug tsc and the language service. These are the two most common entry points into the compiler. In a code editor scenario, as we saw before, the language service sits behind TS Server, which translates messages into language service calls. If you want to debug an editor-related feature like a code fix (e.g., inserting a missing await), the place to start is in the functions returned by createLanguageService in services.ts. Otherwise, youâre probably interested in the core compiler, which is invoked both by the language service and by tsc.
Both tsc and the language service use the Program object as the entryway into the core of the compiler. It takes some configuration options (usually from a tsconfig.json) and a bunch of file paths and pipe them through the compiler to answer important questions like âdo my files have any errorsâ and âwhatâs the JavaScript equivalent of all this TypeScript.â It does that by using the following major components:
if, &&, "doggo"), and the parser converts those tokens into a tree structure of nodes. (The root node is called a SourceFile.)![\"A](\"https://blog.andrewbran.ch/img/CgduxQ2grN-2047.webp)
![\"A](\"https://blog.andrewbran.ch/img/zFMy1A9c7Y-2047.webp)
If most of that review was new to you, donât worry! You donât need to know much more than that to start debugging, and it will make more sense once you dive in. A lot can be picked up on the fly. But, if thereâs one thing you might not want to skimp on, itâs learning the proper terminology for syntax. By way of example, you might see the construct x ? y : z and think of the term âternary operator,â but this sequence is properly called a ConditionalExpression. TypeScript uses the names from the ECMAScript language specification for grammar productions that are valid in JavaScript, but it can be a little tricky to read, and thereâs no corresponding document for TypeScript-specific grammar. I often use astexplorer.net (language set to JavaScript, parser set to TypeScript) to jog my memory of what a certain syntax is called and how itâs structured. If you need the reverse, and youâre really stuckâyou have a SyntaxKind youâre not familiar with and want to know what code produces itâyou can always read the parser! By way of example, if youâre not sure what a TypeQueryNode is, can you get an idea from this?
function parseTypeQuery(): TypeQueryNode {\n\tconst node = createNode(SyntaxKind.TypeQuery) as TypeQueryNode;\n\tparseExpected(SyntaxKind.TypeOfKeyword);\n\tnode.exprName = parseEntityName(/*allowReservedWords*/ true);\n\treturn finishNode(node);\n}\nSyntaxKind.TypeOfKeyword followed by an exprName of something called an âentity nameâ? Yep, itâs the bit after the colon token in const x: typeof y!
The reason you want to be familiar with proper names for syntax is that the parser, binder, checker, transformer, and emitter are in large part a collection of functions with names in the form [verb][SyntaxKind]. Some examples:
\nparseVariableDeclarationbindCallExpressioncheckComputedPropertyName (GitHub canât render checker.ts, so I canât link to the line)transformEnumMemberemitConditionalExpressionThis is very frequently the strategy I use to start debugging a problem. We should issue an error on x.badProperty but we donât? Look for a function in checker.ts called checkPropertyAccessExpression. An expando property assignment fails to create a declaration on its container? Assignment is a form of binary expression, and there are only eight references to SyntaxKind.BinaryExpression in the binder, so one of them should be near the culprit.
If you have a test case that emits a diagnostic message (read: red squiggly error) you donât understand, finding the place to set a breakpoint is really easy. Simply run a find-all inside the src directory for a few words of the error message, with spaces replaced by underscores. For example, if you want to find out why you got the message âJSX element 'a' has no corresponding closing tag,â try searching for has_no_corresponding_closing and youâll find it. Set a breakpoint and work backwards by inspecting up the call stack if necessary.
Be aware that substitutions like 'a' in that error are represented as numerals in the diagnostic property (Diagnostics.JSX_element_0_has_no_corresponding_closing_tag), so you might want to avoid areas of the message that look dynamic or highly specific in your search terms.
Finally, now that you know where to pause the debugger, youâll want to be able to inspect the current state of the compiler. Sure, youâre paused on checkPropertyAccessExpression, but is this the property access expression youâre interested in? Here are a few of the most useful tips for determining just what youâre looking at:
Every Node object has a __debugKind property (since kind is just a number) and a __debugGetText() method.
You can get a nodeâs parent node through its parent property. This is really useful in combination with __debugGetText(), as it gives you a printout of the node youâre interested in, surrounded by some context.
You can skip all the way up to a nodeâs source file by its getSourceFile() method. A source file has a fileName property, which is really handy for setting conditional breakpoints.
Many types of object have some sort of bit flags property, set to an inscrutable number at runtime. These usually have an accompanying property like __debugFlags containing a string representation of the flags, but sometimes you wind up in a function with just a variable with the flags value. In those circumstances, you can often find helper functions to format that number into a string under ts.Debug:
![\"A](\"https://blog.andrewbran.ch/img/T65jmIvtjy-628.webp)
You can access a function exported from the ts namespace in another file by writing its fully qualified name in the debug console. I feel like this is worth mentioning because at most places in the source code, you can drop the ts prefix and write functions like isIdentifier(node), but in the debug console, you have to write ts.isIdentifier(node).
If this has made contributing to TypeScript feel less daunting, peruse through the issues labeled âgood first issueâ or âhelp wanted.â Maybe youâll find something that inspires you![3]
\nVS Codeâs docs on debugging are good if youâre not familiar with it. â©ïž
\nIâm not sure why the debugger starts in the built tsc.js file instead of the source tsc.ts file, but once you step into a different file, the debugger will bring up the TypeScript source instead of the built JavaScript. â©ïž
\nOrtaâs typescript-notes also serve well as a first-time contributerâs guide. â©ïž
\n![\"Loaded](\"https://blog.andrewbran.ch/img/-uIxlNWik3-5400.jpeg\")
âOh! Agh!â are the profound words with which I take the first pedals of a thousand mile bicycle tour across New Zealand. Two years ago, Jeb and I completed a trek of comparable length in Scandinavia, my first bike tour. I remember the first few pedal strokes of that trip as a highlight of the adventure: months of planning and the tedious logistics of schlepping a bicycle and two panniers of camping gear from San Francisco to Norway had come to fruition, and finally my world was simple. All I had to do was move my feet in a circle for two weeks. Now, though, Iâm rolling out of Auckland International Airport with a rather different feeling. An unlikely mixture of panic and bewildered amusement shoots adrenaline through my veins. Itâs midnight, itâs raining, and I have just turned into the oncoming traffic lane. Cars drive on the left here.
\nOf course, I knew that, on some intellectual level. But as it turns out, learning a fact about traffic patterns six weeks ago does not exactly prepare you to fight your entire lifeâs experience of driving and riding on the right side of the road. Especially not in the dark. And the rain.
\nWe ride our first three miles (five kilometers, I remind myself) to the motel Jeb booked, and I consider other ways in which I might be underprepared for this trip. I havenât been on a real bike ride in months. I commute to work by bike in San Francisco most days, but only a few miles. And itâs been cold and wet lately, so Iâve been taking public transit more often.
\nTo my own surprise and deep gratitude, this kind of physical unpreparedness hasnât been much of a problem in the past. In the months leading up to my Scandinavia tour, I was recovering from an injury and didnât ride much, but didnât have a problem adjusting to the daily rigor of touring. Lately though, it has occurred to me that this unearned and undeserved ability will not last forever. Someday, Iâll get on my bicycle after three months of sitting on the couch, with the intention of pedaling 75 miles, only to find that my muscles have finally and permanently transmuted into pizza and left me to suffer the consequences of my sloth. That day could be tomorrow, it occurs to me. Guess weâll find out soon.
\nâ
\n![\"Jeb](\"https://blog.andrewbran.ch/img/0OZYJi_4KW-4473.jpeg\")
The first days are hard, and I know theyâre probably the easiest weâll have. I take some solace in the fact that Jeb is struggling too, because heâs probably in better shape than I am. This is a normal adjustment period. Nonetheless, itâs a little unsettling when we decide to cut our first day 20 kilometers short, partly because weâre running out of daylight.
\nStill, it feels good to be on the bike. It feels good to be on vacation. I vocalize this sentiment several times during our first day.
\nThe morning of day two, the good feelings are temporarily supplanted by a different one: burning pain. Sunburn. Yesterday was overcast, even with misty rain at times, so I completely forgot sunscreen. My arms and legs are bright red. Idiot.
\nA few hours later, weâre on a short section of gravel cycle path bypassing a busy highway junction. I think about when we took a âgravelâ trail in Norway that we learned later was totally impassable by bike. We pushed our bikes for almost the entire day, but I got a few miles of practice over gravel, rocks, and sand, which is considerably trickier on a loaded touring bike than on a mountain bike. My balance and maneuvering got to be pretty good, and it makes shorter, more manageable trails like this a fun diversion from the typical monotony of asphalt.
\nThus hubris brings me down. As soon as I think that Iâm doing well to be going so fast down this trail, I hit a patch of sand. The bike excuses itself out from under me to the right while I continue, according to the laws of physics, straight ahead and down. Gravel and sand grind into my freshly sunburned forearm, tear through the shoulder of my shirt, and generally leave the right half of my body looking like something out of The Walking Dead.
\nAs I dig rocks out of my sunburned arm and Jeb helps wrap it with gauze, Iâm so annoyed with myself. âWow, youâre out of practice,â a friend had said on Instagram that morning in reply to a picture of my sunburn. Sheâs right. Itâs day two, and Iâm making stupid mistakes that Iâm going to pay for throughout the rest of the trip. I grimly concede that this fall was actually really lucky. For every way it could have gone better, there are ten ways it could have ended my trip. So I try to regard my pain with some gratitude, put those darker hypotheticals out of my head, and pedal on.
\nâ
\nEvery day, without fail, someone asks me, âWhereâd you start this morning?â and each time Iâm caught completely off guard. I feel like one of any dozen amnesic movie characters who awakes in an unfamiliar world and must struggle through the most basic human encounters as he tries to reassemble the pieces of his forgotten life. âUm. Iâm not sure. What year is it?â Put on the spot, I have no memory of this morning. My body is trying desperately to keep my vital organs functioning in spite of the abuse Iâm administering it, and there just arenât enough resources to go around. All non-essential personnel have been escorted from the premises. The short-term memory department is vacant. My insides are squirming as I find myself utterly incapable of answering what was surely not intended to be a trick question.
\nEven if I could readily recall what my campsite looked like or what I ate for breakfast, I still wouldnât be able to summon the name of the town. New Zealandâs largest cities have almost caricatural British names: Queenstown, Christchurch, Wellington; but nearly everything else is named in MÄori, a language that shares its name with New Zealandâs earliest inhabitants, Polynesian settlers who arrived by canoe in the 13th century. The syllables jumble hopelessly in my linguistically Western-accustomed brain, and I have no idea how to pronounce anything. Was it Tokoroa, or Rotokawa? No wait, Rotorua? Turangi or Tauranga? How exactly does one pronounce Waiouru? Hatepe? Rerewhakaaitu? It turns out that if you canât convincingly pronounce a place to yourself as you read it on a sign, youâre not going to remember it when someone asks you ten hours later, âWhereâd you start this morning?â
\nâUm. North. 70 miles north. Um. 110 kilometers.â I canât remember a single detail that would help me identify my extremely recent location on earth, but I can still do fast mental math. My survival mechanisms have weird priorities.
\nâ
\nTaupo feels like a ski resort village grew up and became a town. Granola-chic shops and restaurants line the lakefront, along with a green belt and shared pathway featuring a human-scale, made-for-Instagram block letter sculpture reading â#lovetaupo.â Itâs a breathtakingly beautiful hub either for the modern outdoor adventurer or for someone who intends to become one through enough shopping of outdoorsy brands. Either way, it feels good to be here, as weâre finally seeing our distance from Auckland grow appreciably on the map. The next day, we tackle the longest and tallest climb of the North Island with less strain than we had expected. The weather has been kind so far. Finally, weâre getting in a groove.
\n![\"My](\"https://blog.andrewbran.ch/img/7teeEFPmrS-5204.jpeg\")
â
\nWe awake in Foxton Beach just after the sun, our gear soaked through with dew. Australian magpies haunt the campground with their other-worldly songs. Barring catastrophe, it will be our last day on the North Island. The last few have been strong, and we can taste the sweetness of such a significant checkpoint already.
\n![\"A](\"https://blog.andrewbran.ch/img/z2ZeLXDb_Z-3902.jpeg\")
We ride a frigid few kilometers to the local cafe for breakfast. These cafe stops are one of my favorite parts of these trips. Iâm well aware of the privileged white tourist stereotype this makes me resemble, but I think itâs defensible here: New Zealand takes breakfast seriously. We enter the cafe minutes after it opens, rubbing our hands together for warmth. Piano Man is blaring over the sound system, which feels oddly perfect. In every other way, itâs an archetypal beach cafe for a sleepy beach town, with distressed wood tables and pastel walls. Everything about it is bright and warm and adorable, including the owner. She greets us and brings us each a flat white. Feeling returns to my fingers as I cradle the mug in my hands. I think Jeb is in love.
\nBreakfastâEggs Benedict with prosciutto and sautĂ©ed spinachâlooks like something you might find in a Michelin star restaurant. In the States, a place with this casual of a vibe can be expected to serve bran muffins. Oatmeal at best. Jeb notes his observation about Kiwisâ devotion to breakfast foods to the owner, who tells us her passion for breakfast is so great that when she opened the cafe, she intended to serve it all day. But alas, her husband, the full-time professionally trained chef, refuses to poach an egg after 12:00 PM. As I shovel the deliciously and artfully prepared egg and prosciutto into my mouth, thereâs no denying her husbandâs culinary prowess. But I canât help thinking that, given the chance, Jeb would probably poach her an egg at any time of day or night.
\n![\"A](\"https://blog.andrewbran.ch/img/Lm8ZPcoLQN-4032.jpeg\")
â
\nAt the beginning of these kinds of trips, I feel a little self-conscious when we intersect too sharply with civilization. We donât often smell great, we look ridiculous, at any given moment itâs nearly inevitable that somehow Iâve smudged chain grease onto my face, and whenever we enter an establishment, we surreptitiously scan the room for power outlets to charge the small army of dying electronics weâre cradling in our arms. We look like two homeless men in skin-tight clothing. It can be a little uncomfortable.
\nAfter about three days, though, something magic happens: all self-consciousness dissipates to make room for some brand of delusional confidence, probably born of the necessity to avoid freaking out about the hundreds of grueling miles that lie ahead. By the time we reach downtown Wellington, where weâll catch a ferry to the South Island the next morning, this confidence is running high and inhibitions are running low. Which is a good thing, because all the accommodations close to the ferry terminal are, well, not quite ritzy, but theyâre places with porters and concierges and very modern looking lobbies attached to moodily lit bars. Iâve reserved us a room in one of these hotels, so when we pull up, Jeb stays outside with the bikes and I walk in. A week ago, this would have felt like a nightmare: walking into here looking like this. But now, having just completed 430 miles (around 700 kilometers, I remind myself, in case the girl checking us in is impressed and wants to know), clear from one end of the island to the other, Iâm strutting into the lobby in my size-too-small bike shorts and fingerless gloves feeling kind of awesome instead of mildly bashful.
\nNo one asks how far weâve come, but Iâm sure theyâre impressed anyway.
\nâ
\nSomeone once asked me the totally reasonable question of what Jeb and I do while riding, how we pass the long hours in the saddle. Do we ride side by side? Do we talk?
\nTraffic usually constrains us to riding single-file, which makes conversation difficult. Itâs impossible to hear each other when a car is passing (much less a semi full of sheep), so depending on the conditions, it can take a while to get through a single sentence. Most sentences just arenât worth the hassle.
\nJeb likes to watch our progress on the elevation profile to prepare himself mentally for climbs. I listen to podcasts sometimes, with a single AirPod in the ear that faces away from traffic. But the best way to pass the time is to let your mind fall deep into some train of thought you can get totally lost in. These are the times when double-digit miles can disappear without notice. For me, this often takes the form of replaying events from the last few days over and over in my head, trying to uncover thoughts and stories to write about later. Psychologists call this mental repetition elaborative rehearsal, and it plays a significant role in forming long-term memories. I like to think that the long, mindless hours help me remember the highlights of these trips forever.
\n![\"Looking](\"https://blog.andrewbran.ch/img/WN2lFr4kNO-5400.jpeg\")
Perhaps the most compelling reason to ride single-file, though, is that itâs easier. Drafting off another cyclist, minimizing the force of air resistance on yourself, makes the work significantly easierâup to 50% easier at high speeds or in the face of a strong headwind. Plus, trying to keep my front wheel within inches of Jebâs rear wheel without causing an accident is a surprisingly effective distraction for passing the time. I used this advantage extensively on the North Island, which Jeb had planned and therefore navigated, riding in front most of the time. But now, on the South Island, it was my turn to ride in front. The increased wind resistance is a rude awakening, and most of the time, Jeb inexplicably rides several meters behind, seemingly throwing away the priceless gift being extended to him by the physics of fluid dynamics. Itâs tempting to point out that if heâs going to work that hard, he may as well continue to ride in front so I can draft. But, thatâs not how this works. My job now is to navigate to Queenstown, and Jeb can ride wherever he likes. He would even probably switch with me from time to time if I asked, but I want to uphold my end of this tacit agreement with the same grace that he did.
\nUgh. Grace and maturity are so hard when youâre tired.
\nâ
\nA few days into the South Island, Iâm beginning to worry that the window between hitting my stride and deteriorating into crippling fatigue might be closing rapidly. Weâve been riding for ten days without a day off, and while the South Island offers a reprieve from the heavier traffic of the North Island, it brings bigger climbs, longer stretches without food or water, sand flies, and bees. Everyone told us how beautiful the South Island is; nobody told us itâs infested with bees. Sometimes itâs impossible to stop and rest without getting swarmed. Jeb and I both have stings, bites, and healing sunburns that make it hard to sleep some nights, compounding the mounting exhaustion the next day.
\n![\"A](\"https://blog.andrewbran.ch/img/1EAVKXfgBY-5400.jpeg\")
As we leave St. Arnaud and head toward the West Coast, Iâm expecting an easy day. Yesterday we spent the whole day climbing from sea level to several thousand feet, and today weâll do the opposite, reaping the reward of the hard work we put in. Right?
\nNo such luck. The descent is gradual and rolling, and a strong headwind pushes against us the entire day. I have to pedal hard to make forward progress down the hillsâIâm convinced that if I coasted, Iâd be blown back up in reverse. It feels like a personal affront, like Iâve been robbed of something I earnedâno, something I made for myself through a tireless labor of love. The day is, in fact, probably easier than several weâve put behind us, but the dissonance between expectation and reality is devastating.
\nWe pull into our camping spot at 8:00, our latest arrival yet. Itâs dusk, and the air is dark with sand flies that commence biting as soon as we stop moving. Why do I do this?
\nâ
\nI stand in front of my tent, facing south, and switch off my headlamp. Giving my eyes a moment to adjust, I hear the faint rush of the Buller River behind me. The air is cool and damp, and the sand flies have retreated back to wherever bugs go at night. Then, I look up and gaze out into the universe into a direction Iâve never looked before.
\nThe International Space Station floats by, leading my eye east across constellations and galaxies Iâve never seen: the Large Magellanic Cloud, faintly visible. The Southern Cross. Centaurus, Corvus, Crater.
\nSince I can remember, Iâve felt a child-like wonder at the vastness of the cosmos while staring at the stars in the northern sky. Now, pinpricks of light from countless billions more meet my eyes for the first time, as if to say, You have no idea what vastness is.
\nOh, right. This is why I do this.
\nâ
\n![\"Distinctively](\"https://blog.andrewbran.ch/img/iiAELqqe2K-3581.jpeg\")
The weather turns wet along the West Coast, alternating between rain and the threat of rain. Iâve planned for us to take our first and only day off at Fox Glacier, which my body desperately needs. Every morning, my legs threaten to go on strike, and a more insidious pain creeps into my lower back after five to ten miles of continuous riding, and becomes unbearable after five more. A ten-minute stretch break seems to fend off the pain for another ten miles or so, but Iâm worried that these breaks will have to become longer and more frequent to have the same effect, especially once we head back into the mountains. Jeb and I are fairly well-matched in pace, and stamina, and stubbornness, so the idea of giving up or radically altering our plans has really never come up before, which makes this creeping pain all the more terrifying. I donât want an injury to force that conversation.
\nWhenever I find myself in a situation like this, I tend to convince myself that I have no pride to lose over the matter, that I have nothing I need to prove to myself. In 2014, I completed an Appalachian Trail thru-hike, five months walking through woods and over mountains from Georgia to Maine. Only a few hundred people a year successfully complete a thru-hike, and I had no idea if I had what it takes when I started. Ever since, Iâve been able to use that success to reject the idea that I have to overcome every next extreme physical challenge in order to maintain self worth. Sometimes itâs a healthy tool that helps me avoid the risk of injury, and sometimes itâs just a barrier for my ego.
\n![\"In](\"https://blog.andrewbran.ch/img/TAwE465LL0-3581.jpeg\")
When we arrive in Fox Glacier, I make the call that we canât take a day off. Even though Iâm terrified that my body might just shut down at the foot of the next hill we encounter, thereâs a more dangerous forcing function to consider. We have three days of riding left, the last two containing mountain passesâHaast Pass and Crown Range Passâand storms are forecast four days from now. If we take a day off, we could very well end up on steep and winding climbs and descents in the rain, with wet roads, low visibility, and heavier traffic as we approach Queenstown. We have to keep moving.
\nI canât exactly explain how or why, but during the following day, something shifts in my mind. Even though Iâm exhausted, Iâm feeling confident, even excited, about the challenging terrain ahead. Realistically, Fox Glacier was my last chance to give up or change course, and it feels good that it was fully my decision to keep going, even to turn up the heat by eliminating our rest day. Two more days sounds doable. I can endure anything for two days.
\n![\"A](\"https://blog.andrewbran.ch/img/AQC60Fwajb-5400.jpeg\")
The last two days and their monstrous ascents are definitely the toughest of the trip, but the closer I come to the finish line, the more unflappably optimistic I become. Haast Pass nearly does Jeb in, so I don enough positivity for both of us. We each do the same physical work day after day, carrying our own bodies, bikes, and gear for 75 miles over thousands of feet of climbing, but we bear the psychological burden in shifts. A few days ago, I might have given up if not for Jeb. At this point, he would still succeed without me, but it feels good to be the one pushing us forward to the end nonetheless.
\nAnd so, as Queenstown comes into view and we cross the thousand mile threshold, I realize I was wrong. As soon as I doubted my ability to make it, I did have something to prove to myself: not that I could continue to spin my feet for another 200 miles, but that I could overcome the obstacle of fear and doubt and make those miles a highlight of the trip, that I could be awestruck by the spectacular beauty of the surrounding glacial landscapes instead of being consumed by my own discomfort, and that I could keep our spirits high when Jeb needed encouragement instead of dragging both of us down.
\n![\"Jeb](\"https://blog.andrewbran.ch/img/ghBio55WFQ-5400.jpeg\")
Someday, I will lose the ability to bike a thousand miles in 16 days without training, but I hope I donât lose the ability to take charge of my own happiness and find the beauty in challenging circumstances. It takes practice. Itâs a muscle that has to be trained and exercised sometimes.
\nNext time, Iâll try to prepare with some actual training too, and get on the bike some before setting out. Probably.
\n![\"View](\"https://blog.andrewbran.ch/img/L6I5KeluqZ-5400.jpeg\")