💌📯 Updates

[orta]

If you are interested on updates to the TypeScript web infra, you can subscribe to this issue by clicking down and to the right. I'll comments with project updates. I try to do 3 days on web infra, and 2 days on compiler things a week, so there should be some progress every week or two.

If you're on a mobile, I'd recommend only loading this page on WIFI, the GIF usage is pretty intense.

Long term roadmaps:

• Website Vision Website Roadmap  #94
• Internationalization Website Internationalization Roadmap #100
• Community Section Community Section of TypeScript Website  #63

A lot of progress happens on the v2 branch of the TypeScript website repo, the results of this is attached to the main website under a folder called v2: https://www.typescriptlang.org/v2/

Please don't comment in this thread (you're welcome to poke me on Twitter ( @orta )) - I'm trying it unlocked to let reactions stick around so that it doesn't feel like shouting into the void.

Subscribe

                       ----------------------------------------------------------->

About myself 👋

Hello there, I’m Orta! I'm reasonably new to the TypeScript team, and have been focusing on docs and web tooling. You can find more fine-grained updates on twitter.com/orta (plus y'know, other stuff) - also, thanks for the idea https://github.com/octokit/rest.js/issues/620

[orta]

November Catch-up

I have two not yet published blogs posts on the TypeScript product blog, one on our usage of GitHub Actions in the Playground in the repo orta/make-monaco-builds, and an overview of the v2 of the TypeScript playground. The TLDR, because I have no clue how long these posts will be in publishing quagmire:

• Automatic Type Acquisition (beta) - the site will grab the d.ts files for your imports
• Comprehensive Examples - 40+ focused docs on different parts of TypeScript
• Example Hyperlinking - Examples can link between each other
• Concise hrefs - The URL is a gzipped string of the code, with all compiler flags etc
• Decoupled TypeScript Versions - You can test many versions of TypeScript
• Theming Support - from @keithlayne
• JavaScript Playgrounds - So you can help each other with JSDoc support
• Fixits - Mainly so we can document new fixits on a release
• PR Based Playgrounds - Any TS team member can request a playground for a PR via commenting
• Export to ... - Take your current context and send it to places like Code Sandbox or StackBlitz

The playground self-documents a lot of these in a set of examples

Long term

On the website v2 side, I've created larger roadmaps which talk to some of the long-term vision on different parts:

• Website Vision - this includes links to all the designs too
• Internationalization
• Community Section

Work in Progress:

• I've got a good chunk of the v2 website navigation working with the current handbook
• I've built out a library which can power the TypeScript-powered Code Block which isn't hooked up to the v2 markdown pipeline yet
• I've built a lot of infra for an internationalized TSConfig reference - which I'm in the process of adding examples and richer descriptions to all keys. PR's welcome there.

Shipped Infra I'm happy with:

The new website has a solid amount of automation:

• PR based deploys of the site
• Lighthouse results for a few pages
• A danger-js plugin for showing lighthouse results
• I extended the danger-js plugin for spell checking to also include code
• This post auto-comments into the TypeScript Teams channel via GitHub Actions

Thanks

• @keithlayne for the theming support into the playground
• @br1anchen for the work on adding export
• @agentcooper for the typescript-play repo which the playground forked from

[orta]

Website Navigation

I've focused my work with three main goals since the last update:

• Documentation for the TSConfig
• Tooling for how we want to show code blocks
• Creating the navigation shell of the website so that we can preview pages

I'm going to focus this update on the navigation aspects of the site. Let's look at a few different places we have navigation and talk about why it was designed this way

Site Navigation

I tried to take a mix of modern native mobile app design, and website best practices to focus on three main audiences:

• Desktop with mouse
• Desktop via keyboard
• Mobile Phones

The first two tend to have similar needs in terms of what they want for site navigation, but mobile devices themselves should be treated quite differently both from a user's intent and how we should present navigation.

How does it look on desktop?

How does it look on mobile?

Why the drastic change?

Navigation on desktop tends to take a lot of design cues from headers in print design which aims to follow the path of reading:

1. Have a strong visual distinction for a section of links
2. Always have a brand mark link in the top corner where folks read from which takes you to the index
3. Include a few links to the important places next to that
4. Include a flexible whitespace gap then have secondary tiered navigation links at the end of your eye flow

But mobile really disrupted that from two factors:

1. The horizontal space is so constrained, good luck getting more than 4-5 words in there
2. There are 'blessed' areas of the screen where it is physically easier to touch once mobile devices got big

This moved the design frames of references from one loosely based on fitt's law to
one based on thumb touch maps.

From scotthurff.com

In designing for mobile, I had to really narrow the priorities for people to two things. I wanted people to easily get to search, and to go to the root of the documentation. In my experience building websites for developer documentation, most people are using mobile as a reference or to quickly show something to someone.

You can see here that we barely get into the natural section in search

Then just get comfy when the navigation bars appears

( thanks Thuy Gia Nguyen for the heatmap)

With the navigation designed, I applied the same forms of navigation hiding which mobile browsers do. The navigation will only show when you start to move up. It also keeps track of display curves for phones like the iPhone X and my Samsung Note, you can see in this GIF when the browser includes a flat edge at the bottom then the navigation buttons lay flat.

I still have a few questions to answer though:

• What will the language selector look like?
• What will the theme selector look like?

I expect to take some cues from docs.microsoft.com.

Footers

I believe in mega-footers. A footer is the end of the information you were actually looking for and generally represents three things:

• A jump-off section for people to get to related links
• Calls to action for something you want your users to do
• A place for tertiary links (1st: site nav, 2nd: related internal links, 3rd links you need to have somewhere but don't need design weight)

With the TypeScript footer, to handle the I took a look at the most popular documentation pages on the website and included them to make sure that people would have easy access to them. Their order is in popularity.

To hit the second, I wanted to raise the visibility of the playground code samples. These provide a very focused explanation of many parts of how TypeScript works and aren't easy to find as a sub-navigation element inside the playground. When viewport to the site is large enough, and JavaScript is enabled then the Code Samples link switches to a popover which echos the design in the playground.

For mobile, I didn't need to do anything content-wise. I don't think there's any value in making it more focused. Design wise I only made a few tweaks but it felt fine in both.

Internal Navigation

The other place where we have navigation is between pages. When you link into a handbook, we want to show a navigation between related documents.

This is a pretty solid design pattern to work within, and one that's common on documentation sites. I took care to make it obvious which navigation section you're in and Gatsby made it so fast that it doesn't feel like you're navigating between web pages.

The tricky thing was making it feel right on keyboard, which I'm really happy with.

No runtime dependencies

A lot of what you're seeing in these screenshots looks like a lot of complicated JavaScript code, but it's not. Apart from search which comes from Algolia, the v2 site has zero JavaScript dependencies at runtime, and is a static HTML site to an azure blob storage account.

The interaction patterns are built from first building the site with JavaScript disabled, and then JavaScript to handle some of the extra is added in at runtime. I use the useEffect pattern inside a React component to add client-side JS enhancements. For example here is all the runtime JavaScript code to handle allowing the popover in the footer. The rest is all CSS.

This pattern works really well for a medium sized site with only 1-2 core contributors.

[orta]

Interactive Codeblocks

It's been a slow week on the web infra and docs world. The tsconfig docs are pretty close to being wrapped up now. However, the main reason for the slow week has been that I was on my first Definitely Typed rotation last week, and I'm covering mornings this week.

In-between DT work, I've been wrapping my head around twoslash improvements. Twoslash is a mini-typescript sandbox environment where you can control the compiler and the output via comments. It's part of a larger roadmap #120 but it's basically the tool doing the heavy lift.

For example:

// @declaration: true
// @showEmit
// @showEmittedFile: index.d.ts

/**
 * Gets the length of a string
 * @param value a string
 */
export function getStringLength(value: string) {
  return value.length
}

Tells the compiler with the first three lines:

• Set the compiler option declaration to true
• Set the twoslash optionshowEmit to true (meaning that the code sample should show a different file and not the source TypeScript)
• Set the file which it should show to be index.d.ts

So the user-facing code sample would be:

/**
 * Gets the length of a string
 * @param value a string
 */
export declare function getStringLength(value: string): number;

This means the code sample a user see is a .d.ts for a .js file, instead of the original source code.

Twoslash Features

• Showing errors from the code sample, and leaving the messaging to the compiler
• Declaratively highlight symbols you want to show
• Handling showing the results of transpilation with certain flags
• Splitting a code sample to hide distracting, or redundant code
• Support an example referencing multiple files
• Creating a playground link for the code

For us the critical stuff is showing errors, highlighting parts of source code and showing the results of transpilations. The nice to haves are things like handling imports in a single file, and playgrounds.

The advantages for the site are:

• We can be sure TS emits, and error messages are always accurate between TS releases
• We can do callouts in docs to show the exact results of a particular identifier

This last point is particularly useful because of how TypeScript type inference works with narrowing or widening - the same variable identifier could be very different objects in different parts of the same code sample.

Highlights for you, and you, and you

While it's great for us to highlight the bits we think are important in a code sample, the ideal state is that our code samples provide a way to highlight the code at all the identifiers in that sample. This is one of the features I've been working on this week:

While not 100%, you can feel all of the pieces coming together:

Ecosystem Adoption

Nearly all of these twoslash features aren't problems unique to TypeScript, twoslash uses the language server protocol to extra all of these annotations - meaning essentially any language can re-create this infrastructure in their docs (and hopefully after seeing it on the TypeScript v2 site, they will!)

I've also been building twoslash support out as a series of modules to work with Gatsby, so I would hope this makes it easy for folks to use adopt twoslash for their sites when they are writing about TypeScript.

[orta]

TSConfig Reference

One of the completely new features in the new website is the TSConfig Reference. Since the last update, this page is now at a "good enough" stage that it's pretty publicly available. The design is a WIP, but the copy is 👍.

https://www.typescriptlang.org/v2/en/tsconfig

The TSConfig Reference has a few goals:

• De-mystify the configuration for TypeScript by providing more comprehensive examples per flag
• Have examples for compiler flags use the compiler to show how the flag works
• Make it easy for the community to contribute and improve the tsconfig docs
• Provide a path for internationalization

De-mystifying Compiler Flags

Prior to the TSConfig reference, the canonical source of information on the available flags and how they work is the overview of the command line flags for TypeScript. This is/was a table of tweet-sized descriptions of most CLI flags, of which the majority are also tsconfig options. You would then likely need to either get information from the release notes which introduced that flag, or to search the internet for that exact flag name to get more info.

This documentation structure is pretty logical because the TypeScript codebase keeps both tsconfig and CLI flags in the same data-structure, which has made it hard to extract either for documentation purposes.

My first port of call at starting this page was to use the typescript API to extract all of the compiler flags and to generate a JSON dump of all the compile flags. This comes to about 100+ flags today.

export type CompilerOptionName =  "help" | "watch" | "preserveWatchOutput" | "listFiles" | "listEmittedFiles" | "pretty" | "traceResolution" | "diagnostics" | "extendedDiagnostics" | "generateCpuProfile" | "incremental" | "locale" | "all" | "version" | "init" | "project" | "build" | "showConfig" | "listFilesOnly" | "target" | "module" | "lib" | "allowJs" | "checkJs" | "jsx" | "declaration" | "declarationMap" | "emitDeclarationOnly" | "sourceMap" | "outFile" | "outDir" | "rootDir" | "composite" | "tsBuildInfoFile" | "removeComments" | "noEmit" | "importHelpers" | "downlevelIteration" | "isolatedModules" | "strict" | "noImplicitAny" | "strictNullChecks" | "strictFunctionTypes" | "strictBindCallApply" | "strictPropertyInitialization" | "noImplicitThis" | "alwaysStrict" | "noUnusedLocals" | "noUnusedParameters" | "noImplicitReturns" | "noFallthroughCasesInSwitch" | "moduleResolution" | "baseUrl" | "paths" | "rootDirs" | "typeRoots" | "types" | "allowSyntheticDefaultImports" | "esModuleInterop" | "preserveSymlinks" | "allowUmdGlobalAccess" | "sourceRoot" | "mapRoot" | "inlineSourceMap" | "inlineSources" | "experimentalDecorators" | "emitDecoratorMetadata" | "jsxFactory" | "resolveJsonModule" | "out" | "reactNamespace" | "skipDefaultLibCheck" | "charset" | "emitBOM" | "newLine" | "noErrorTruncation" | "noLib" | "noResolve" | "stripInternal" | "disableSizeLimit" | "disableSourceOfProjectReferenceRedirect" | "noImplicitUseStrict" | "noEmitHelpers" | "noEmitOnError" | "preserveConstEnums" | "declarationDir" | "skipLibCheck" | "allowUnusedLabels" | "allowUnreachableCode" | "suppressExcessPropertyErrors" | "suppressImplicitAnyIndexErrors" | "forceConsistentCasingInFileNames" | "maxNodeModuleJsDepth" | "noStrictGenericChecks" | "useDefineForClassFields" | "keyofStringsOnly" | "plugins";

Having a data-dump is a good first start, but some of these flags are obviously CLI only, for example: "help" or "watch" and the graph of these options is quite complex but not represented in the TypeScript codebase.

To map these domains, there is a file called tsconfigRules.ts which strives to be the source of truth for how the config options connects and their additional metadata.

This file tracks:

• Denylisting CLI only options
• Available options for a flag
• Defaults for the flag
• many to many relationships between options

From there the next step is to generate a markdown file for the site to work with. This is done in generateMarkdown.ts.

Real use-cases

The TSConfig reference is a perfect place for building out the features of the twoslash because it requires making code samples which have all sorts of emits, compiler failures, and configuration options.

A great example of this is the module option - where the same code is ran with different settings for module and creates drastically different JavaScript. It makes it much easier to understand once you can see the outcome alongside.

Low Barrier to Contribute

Each compiler option is a unique markdown file which will eventually be concatinated into a single file. This means a contributor can easily make isolated changes to just the file they're interested in. Because it's plain old markup and twoslash is reasonably simple then we can get a lot of bang for a small amount of code.

Being a series of markdown files means that tooling like Danger can run spellcheckers, and linters against each file individually to ensure we're shipping great docs.

Ready for Translations

This project was built with internationalization from day one. I've been making a really bad language attempt at supporting a l33t speak dialect under "vo" to prove the system:

https://www.typescriptlang.org/v2/vo/tsconfig#module

The idea is that the community can add translations option by option, and if they haven't included one yet then the english version is the fallback. So while it might be simple - it works well and it's the first part of the v2 website to hit all three of the targets for the internationalization roadmap.

Meaning it's ready to go it you want to start translation to a language you know. Docs are in the README

[orta]

State of the v2nion

(How I feel after the winter holidays)

type State = "playground" | "internationalization" | "dev-pages"

I've been plugging away occasionally on the last two weeks on the new Playground, and some developer pages for the node modules which I needed for the website. I'll cover those later, but now that we've hit the 3.8 beta, it's time for me to slow down on the web infra to work on some compiler bugs. So, unless I feel like deep-diving on a particular topic there may not be an update in 2 weeks time.

Localization

I originally started working on supporting multi-lingual content for the site about 5 months ago, when I was doing my initial work on forking TypeScript-play to be the new TypeScript Playground. The site was still in design phase, but it felt like an achievable goal, if done in small steps regularly while any type of content was being made.

That said, localization for v2 actually came with three interesting problems:

• What do you do with URLs? To treat all languages equally, a page like /community should be /en/community but that makes it tricky with losing existing SEO for these pages. We host statically, and I'm not sure if we can make HTTP redirects
  work with Azure Blob Storage.

• How do you handle fallbacks when some content for a localization isn't available? E.g. someone has translated a page of the playground, but not the tsconfig reference. The footer links from the playground should correctly redirect to the english fallback, and not to a non-existent page.

• Where should localized content live? Right now it's all in the main TypeScript website repo, and given that I account for nearly all PRs on the repo, it's not a massive hub of activity. However, you want to give ownership to translators and you want to be sure that code won't break the whole website. Right now, the other developer websites with a similar set of constraints (size of documentation, potential contributors, complexity in domain) like React use multi-repo approaches.

  Right now my technique of keeping it in the TypeScript repo is a little ad-hoc, but I'm keeping my eye on how Gatsby handles their translation efforts to see if there is work we can share.

  You can see an example of what adding a language looks like here.

Playground

I gave a TL:DR on the main changes to the TypeScript Playground v2 back in Novemeber, but now we have Playground v3. This has about 90% of the features of the v2 playground,
and a few extra nicities:

• It's now all in TypeScript and has some tests, as opposed to a single massive .JS file
• The Sidebar UI is built for expansion (it is a plugin system, so people can create their own plugins in the future)
• The code is split into "Sandbox" and "Playground", the sandbox being a monaco-editor wrapper and Playground as the
  comprehensive UI for configs, examples and the sidebar.
• It runs entirely on our infrastructure (except the type acquisition)
• Type Acquisition now caches into localStorage, and so it should be pretty instant after the first time
• There are options, so you can turn off updating the URL when you type, or ATA (and more later)

The playground was the first thing I designed for the TypeScript v2 website, and so it's nice to finally see and use it. I reflected earlier on twitter about how design work can feel like a rough plan, because the moment you start iterating - you have a much better set of assumptions about how something works.

Dependencies For Others

I mentioned the Sandbox above, I've taken some of the larger dependencies and given them their own section of the website. Both of these are really useful tools if you're working with TypeScript on the web, so I wanted to highlight tooling we've made as quick overviews,

• https://www.typescriptlang.org/v2/dev/sandbox/
• https://www.typescriptlang.org/v2/dev/twoslash

I'm sure there are a lot of other cool modules the TypeScript team have shipped, so I want to try highlight how to work with the TypeScript compiler API and some other useful tools.

Current Sitemap

• Existing Handbook Content: https://www.typescriptlang.org/v2/docs/handbook/basic-types.html (just this page has twoslash enabled)
• Docs root: https://www.typescriptlang.org/v2/en/documentation/
• TSConfig Reference: https://www.typescriptlang.org/v2/en/tsconfig
• Playground: https://www.typescriptlang.org/v2/en/play
• Dev page, Sandbox: https://www.typescriptlang.org/v2/dev/sandbox/
• Dev page, Twoslash: https://www.typescriptlang.org/v2/dev/twoslash

My aim once I get back to the site:

• Index page
• Infra for localized Handbook content (though I'll not recommend folks actually translate them because a v2 for the handbook is still in the works)
• Dark & High contrast modes
• Initial polish passes for design, keyboard accessibility

[orta]

HQ vid

Why Gatsby?

The TypeScript v1 site is a jekyll website, and Jekyll packs a lot of power into a small tool. Jekyll is really great way to build static websites, but it's built to work for small websites of around 1-20 pages.

You can feel this in how they treat templating (liquid, which is a logic-less templating engine), how they treat the data modelling internally (there are only really 'Posts' & 'Pages') and how the tool is set up to work with a specific folder structure.

At Artsy, where I worked at before TypeScript, we had started to hit the limits of working within Jekyll at around 200 blog posts and a lot of custom pages, and we were exploring different tools to use as a writing environment. In the process I looked deeply into Gatsby, and concluded that it was the right abstraction for building static sites.

What Makes Gatsby Unique

What makes Gatsby unique among static site generators is this idea that it adds an extra step to the process. In a normal static site generator, you would more or less directly map files to their output:

const files = fs.getDirSync()
const htmlFiles = files.map(makePage)
htmlFiles.forEach(html => {
  fs.writeFileSync(filename, html)
})

Gatsby on the other hand does something a bit more like this:

const setupSite = () => {
  const files = fs.getDirSync()
  const data = files.map(makePage)
  graphQLServer.add(data)
}

const createBlog = () => {
  const pages = graphQLServer.query("{  pages { title, text } }")
  const htmls = pages.map(renderComponent)
  htmls.forEach(html => {
    fs.writeFileSync(filename, html)
  })
}

setupSite()
createBlog()

Gatsby adds a GraphQL API which sits in-between the setup of the data and the generation of files in your static site. This abstraction providing a very strong separation of "setting up the site" vs "representation on the file system" which I've found makes it easier to reason about what's going on internally.

What does this look like in practice? It starts at gatsby-node.js but an interesting example is how a TSConfig Reference page is set up:

• In the Gatsby config file, we request a plugin to look for markdown files in a particular folder and to mark them as tsconfig-reference
• Then in onCreatePages in gatsby-node.js we make a GraphQL query to get all these files via the name "tsconfig-reference".
  These files are then used to create Pages inside Gatsby (e.g. en.md => /en/tsconfig, pt.md => /pt/tsconfig) and we link the React component used to render them.
• Once all of the pages are set up, Gatsby runs through each page.
• For the TSConfig it would load this template, run this query,and pass the results as the initial argument to this function - it does this per language.

It's a few more steps then mv ../tsconfig/en.html en/tsconfig.html - yep, but once you grok the larger idea then each step is a well composed, isolated and easily tested part of a larger system. That's what makes Gatsby a great abstraction.

Types For Tools

The TypeScript support in Gatsby is good, and improving as they start to port their own codebase to TypeScript. When I first started, I shipped a few d.ts file improvements and welcome the pings from their team with questions when it changes. In the last 2-3 months, I've been running in a fully typed codebase which has been a breeze.

If you're familiar with React, and clicked through into the TSConfig Template - you might have been a bit surprised by the somewhat unorthodox usage of React.

I'm using React as a templating language, and not as a reactive UI framework, the site never use a setState-like API in React. Effectively meaning React runs once when the site is generated, and then never used again.

My goal is that the TypeScript v2 website, with all its complexity, needs to be understood with the least amount of abstractions possible. It should not be too surprising, but vast majority of the TypeScript compiler team have a compiler background, and don't really do web development. To ensure that they can contribute, and understand the codebase I'm aiming to use Gatsby and React to get as close to HTML + CSS as possible.

One way to do that is to separate the generation of HTML + CSS, from any extra JS which happens at runtime. This means almost every component in the site conforms to this pattern:

// JS imports
import React, { useEffect } from "react"
import { Layout } from "../components/layout"

// Style
import "./tsconfig.scss"

// The main React component
const TSConfigReferenceTemplateComponent = (props: PropTypes) => {
  useEffect(() => {
    // code which happens when the page has finished loading
  })

  // creation of static HTML via React + JSX
  const post = props.data.markdownRemark
  return (
    <Layout locale={props.pageContext.locale}>
      <div className="tsconfig">
        <div id="full-option-list" className="indent">
          <h1>TSConfig Reference</h1>
        </div>

        <nav id="sticky"><ul><li>...</li></ul></nav>

        <div className="indent">
          <div dangerouslySetInnerHTML={{ __html: post.html! }} />
        </div>
      </div>
    </Layout>
  )
}

export default TSConfigReferenceTemplateComponent

// The optional GraphQL query to get info for that page
export const pageQuery = graphql`
  query TSConfigReferenceTemplate($path: String, $tsconfigMDPath: String!) {
    sitePage(path: { eq: $path }) { id }
    markdownRemark(fileAbsolutePath: {eq: $tsconfigMDPath} ) { html }
  }
`

I like this, the rest of the team don't need to learn React - just JSX.

I still get the advantages in tooling because all of this is supported by TypeScript:

• Because JSX support with TypeScript is dreamy, and I love it
• I can still make custom components like Layout which is a custom React component and has the props verified
• The 'runtime' code inside useEffect will be transpiled and verified by TypeScript

By not using any of the React setState-ish APIs, I can guarantee there is no "runtime" React rendering happening on a user's browser. This means the HTML in the built file is exactly what someone will see whether they have JS enabled or not.

One advantage of this has been that I can reliably run BackstopJS to take screenshots of these static files to keep track of visual regressions as the site grows and others start to contribute.

Would I recommend this technique to people making Gatsby websites, probably not, it's going against the grain (React is a really good tool) of how you're expected to use Gatsby. But the trade-off is worth it for me, and I spent some time thinking about that.

Speed

I'm blown away by how fast Gatsby is for a user.

The founder of Gatsby, Kyle Mathews gave a great talk in 2017 on the ways in which Gatsby is fast and here more recently, in rough:

• Prefetching of related links
• Clever splitting of code
• Shrinking of assets
• Offline support
• Native lazy loading

His long term visions is to think of Gatsby as a compiler which takes a set of input source files, and will keep trying to make a static output which is faster and faster for users. Another great resource for understanding the mechanics about why Gatsby is fast is this talk by Nicolas Goutay at GOTO 2019.