microsoft / typescript-website

The Website and web infrastructure for learning TypeScript

Meta

• URLs: production, staging
• Admin: Prod: Azure Portal, Deploy logs, App Insights
• Translations: microsoft/TypeScript-Website-Localizations

Getting Started

This repo uses yarn workspaces with node 13+, and watchman. (Windows users can install watchman via chocolatey)

With those set up, clone this repo and run yarn install.

git clone https://github.com/microsoft/TypeScript-website
cd TypeScript-website
yarn install
code .

# Then:
yarn bootstrap
# Optional, grab the translations:
yarn docs-sync pull microsoft/TypeScript-Website-localizations#main 1

# Now you can start up the website
yarn start

Working on this repo is done by running yarn start - this starts up the website on port 8000 and creates a builder worker for every package in the repo, so if you make a change outside of the site it will compile and lint etc.

Some useful knowledge you need to know:

• All packages have: yarn build and yarn test
• All packages use debug - which means you can do env DEBUG="*" yarn test to get verbose logs

You can manually via GH Actions for production here and staging here.

Having issues getting set up? Consult the troubleshooting.

Deployment

Deployment is automatic:

• Pushes to the branch v2 deploy to staging
• On a Monday the v2 branch is deployed to production

You can find the build logs in GitHub Actions

Docs

If you want to know in-depth how this website works, there is an hour long video covering the codebase, deployment and tooling on YouTube.. Otherwise there are some short guides:

• Converting Twoslash Code Samples
• How i18n Works For Site Copy
• Updating the TypeScript Version
• Something Went Wrong

Website Packages

TypeScriptLang-Org

The main website for TypeScript, a Gatsby website which is statically deployed. You can run it via:

yarn start

To optimize even more, the env var NO_TRANSLATIONS as truthy will make the website only load pages for English.

Sandbox

The editor aspect of the TypeScript Playground REPL, useable for all sites which want to show a monaco editor with TypeScript or JavaScript code.

Playground

The JS code has an AMD module for the playground which is loaded at runtime in the Playground website.

Doc Packages

TSConfig Reference

A set of tools and scripts for generating a comprehensive API reference for the TSConfig JSON file.

# Generate JSON from the typescript cli
yarn workspace tsconfig-reference run generate-json
# Jams them all into a single file
yarn workspace tsconfig-reference run generate-markdown

Validate the docs:

yarn workspace tsconfig-reference run test

# or to just run the linter without a build
yarn workspace tsconfig-reference run lint

# or to just one one linter for a single doc
yarn workspace tsconfig-reference run lint resolveJson

Documentation

The docs for TypeScript. Originally ported over from microsoft/TypeScript-Handbook then intermingled with microsoft/TypeScript-New-Handbook, and finally updated for Twoslash and with new content.

JSON Schema

It's a little odd, but the tsconfig-reference package creates the JSON schema for a TSConfig files:

yarn workspace tsconfig-reference build

Then you can find it at: packages/tsconfig-reference/scripts/schema/result/schema.json.

Playground Handbook

The user-facing documentation for the Playground.

Playground Examples

The code samples used in the Playground split across many languages.

Infra Packages

Most of these packages use tsdx.

TS Twoslash

A code sample markup extension for TypeScript. Available on npm: @typescript/twoslash

TypeScript VFS

A comprehensive way to run TypeScript projects in-memory in a browser or node environment. Available on npm: @typescript/vfs

Create Playground Plugin

A template for generating a new playground plugin which you can use via npm init playground-plugin [name]

Community Meta

Generates contribution JSON metadata on who edited handbook pages.

Playground Worker

A web worker which sits between the Playground and Monaco-TypeScript

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

Legal Notices

Microsoft and any contributors grant you a license to the Microsoft documentation and other content in this repository under the Creative Commons Attribution 4.0 International Public License, see the LICENSE file, and grant you a license to any code in the repository under the MIT License, see the LICENSE-CODE file.

Microsoft, Windows, Microsoft Azure and/or other Microsoft products and services referenced in the documentation may be either trademarks or registered trademarks of Microsoft in the United States and/or other countries. The licenses for this project do not grant you rights to use any Microsoft names, logos, or trademarks. Microsoft's general trademark guidelines can be found at http://go.microsoft.com/fwlink/?LinkID=254653.

Privacy information can be found at https://privacy.microsoft.com/en-us/

Microsoft and any contributors reserve all other rights, whether under their respective copyrights, patents, or trademarks, whether by implication, estoppel or otherwise.

typescript-website's Issues

Debate what to do about replaceState not removing history

I'm pained to remove the current set query hash on a compile behavior because the old way used to lose data for me.

Having the code in the URL is great when you're ready for that, but doing it on every change (or so) fills up your history with fairly useless entries:

See: https://github.com/orta/typescript-play/issues/6

TypeScript Playground doesn't support legacy browsers

TypeScript playground uses globalThis, stage 3 proposal with moderate browser support, a polyfill for it isn't provided. This reduces browser compatibility to evergreens and latest mobile browser versions.

Search Terms:

typescript playground, globalThis

Expected behavior:

Should work in ES6-compatible browsers (Edge, not up-to-date mobile devices, etc).

Actual behavior:

Chrome 68 causes runtime errors:

ReferenceError: globalThis is not defined[Learn More] main-0.js:3:1
menu is null TypeScript_Playground_options.user.js:15:1
ReferenceError: can't access lexical declaration `monacoLanguageDefaults' before initialization main-0.js:735:9

Playground Link: Playground itself

Related Issues:

Playground can sometimes not show all the text on-screen

Resizing and changing the zoom seems to somewhat help, but it's not consistent

Issues with transitive dependencies and multiple files in ATA?

In

import { parse } from "acorn";

parse has an any type, which is unexpected - probably because it's not resolving the estree dependency.

Similarly, if I write

import Vue from "vue";

new Vue({
  /**/
})

even with esModuleInterop, I get a lot of issues where I get no signature help.

Playground eats Ctrl+Shift+I (the shortcut to open devtools) #7

Love the new playground!

Unfortunately, if the playground editor has focus, trying to use Ctrl+Shift+I to open devtools doesn't work anymore. (Tried in Chrome and Firefox.) It doesn't seem to do anything at all.

Would be great if it wouldn't prevent Ctrl+Shift+I.

I can take a crack at it if you'd like, but not for a couple of weeks. :-(

Workaround 1: Use the menu (obviously). :-)

Workaround 2: On Chrome, you can use Ctrl+Shift+J, which still works. (You can on Firefox too, but it opens a new window rather than a docked one.)

Community page in website

I would like to suggest to add a "community page". Something like the following:

There are some communities out there already:

https://twitter.com/typescriptpdx
https://twitter.com/var_tsbr
https://twitter.com/DubTypeScript
https://twitter.com/TypeScriptFR

But I think it would be great to encourage it more 😄

How to capture FAQ's, Gotcha's, and other useful TypeScript details.

Redirecting from the Roadmap issue.

I think there is a large class of TypeScript information that sits beyond the handbook on the complexity scale, but is still far off spec level. This could include FAQ's that arise from particular properties of TypeScript, slightly more detail on certain type relationships, or some of the heuristics TypeScript uses to skip expensive checks.

In general I think this information is hard to find. Most blogs, release notes, and the handbook do not have this information. This is not a criticism---I think it's right that these sources are approachable. My question here is: where does this information belong, if anywhere?

There is an FAQ on the repo that includes many of the gotcha's I'm thinking of, yet they still get asked on the tracker. Maybe the reality is that most people wont read this information anyway, so this is a pointless task. I think that the GitHub wiki is hard to find and hard to digest, so I'm going to assume^*hope that we can improve the situation here.

I have very little experience interacting with developers trying to become competent and master a language, so I feel rather naïve in this regard. I doubt this problem can just be solved by writing a load of content. I'll try and go through a few examples of situations that I think could be improved, though I don't necessary have a strong recommendation of how to improve them (not helpful, I know).

FAQ or Gotcha: Strict function types and methods.

I've seen this question come up a few times, or rather, people posting issues without realising there is such a behaviour: I'm referring to methods always being bivariant. The only places I know where these are documented are in the strict function types PR here, and the release notes for that version of TypeScript here. AFAIK this isn't document in the handbook or FAQ.

My general comment here is that feature PR's often contain a lot of great information in them which is then usually translated to the corresponding release notes, but neither of these should be long-term replacements for specifications of behaviour. PR's can be hard to find and release notes contain lots of unrelated changes. I think there should be a consistent route to transition key PR details into the handbook, web examples, or some other resource. Could there ever be a call for documentation associated with a merged feature PR which is shepherded by someone in the team?

Interesting TypeScript details lost in the tracker.

There are a lot of interesting comments, examples, and discussion in the tracker, but unfortunately that is where it stays. I cannot assert that distilling this information and adding it to the website would have a tangible impact, but to me it feels like users shouldn't have to search the issue tracker to find information that describes the language. If the tracker is presented as somewhere not to ask questions about the language, I think it's reasonable to expect that users shouldn't have to find their answers there. Some examples:

Why is keyof never should be string | number | symbol?

Here is a comment by @weswigham that really nicely describes a particular design choice that I think would provide insight to anyone that reads it. This shouldn't be hidden away in a closed issue, but perhaps associated with some longer exposition of keyof.

Behaviour of writing to an indexed access type.

There was a PR that improved indexed access types but was a breaking change. The change is motivated by some non-trivial reasoning about generics and variance but the description in the release notes was abit short: link. If you follow many of the related issues such as this you'll find lots of interesting discussion and examples. It would be great if some of this content made it into the website: maybe have a playground instance for indexed access types that takes some of these correct and incorrect examples and explains them.

Call Signatures for unions

I've seen a few questions that pop-up when union signatures appear to accept intersection arguments. This was due to this. In my opinion the answer from @jcalz here does a better job an motivating and explaining the change than the example in the release notes here. It would be great to see quality answers that explain why something should be the way it is make their way upstream to the website (or somewhere). I don't know the best medium for this: could it be an FAQ or an example in the playground under union types?

Summary

Despite this wall of text, I think the eco-system is great and I don't intend for this to be negative. I really just want to help people find all the great information that is already out there. I appreciate this it's also likely that you've been through this whole charade before and realise that it just isn't worth the effort: the handbook quite clearly explains distributive conditional types yet people still ask questions about it---some people just don't read docs.

I think my post can probably be summarised as:

• I think information in feature PR's and release notes should not rest there, but be moved into the handbook, website examples, or somewhere else. Maybe you could ask the community to help write the extended documentation for these additions?
• Be more proactive in exploiting quality answers on the tracker (or elsewhere) and updating existing resources. Particularly answers that explain the why, and not just the what. I think it would be nice to give more kudos to great answers too (on the tracker or stack overflow). Would it be reasonable to have a community highlight tweet every month that includes interesting answers by external contributors?

Thanks!

Playground doesn't support async generators.

I put the following code into https://www.typescriptlang.org/play/

async function f(): Promise<number> {
    return 1;
}

async function* g(): AsyncIterator<number> {
    yield 1;
    await f();
    return 2;
}

The compiler reports two errors on the async function *g() line.

• Cannot find global type 'AsyncIterableIterator'
• Cannot find name 'AsyncIterator'

Is that expected?

Website redirection issue

This isn't a TS issue, but an issue with the website www.typescriptlang.org.

When entering typescriptlang.org/play in the browser's address bar you are redirected to the homepage www.typescriptlang.org.

Close this if it's not in the right place.

Playground no scroll

In the https://www.typescriptlang.org/play if you have a lot of text (or a small amount of text on a small window) you cannot scroll to see the bottom. It just carries on and you lose the ability to read what you are typing.

Several loading errors on the non-HTTPS www.typescriptlang.org website

When navigating to the non-SSL version of www.typescriptlang.org, there are several errors shown in the Google Chrome console:

www.typescriptlang.org/:1 Access to Font at 'http://i.s-microsoft.com/fonts/segoe-ui/west-european/normal/latest.woff' from origin 'http://www.typescriptlang.org' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource. Origin 'http://www.typescriptlang.org' is therefore not allowed access.
www.typescriptlang.org/:1 Access to Font at 'http://i.s-microsoft.com/fonts/segoe-ui/west-european/semilight/latest.woff' from origin 'http://www.typescriptlang.org' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource. Origin 'http://www.typescriptlang.org' is therefore not allowed access.
www.typescriptlang.org/:1 Access to Font at 'http://i.s-microsoft.com/fonts/segoe-ui/west-european/semilight/latest.ttf' from origin 'http://www.typescriptlang.org' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource. Origin 'http://www.typescriptlang.org' is therefore not allowed access.
glyphicons-halflings…ular.bc0cf52d.woff2 Failed to load resource: the server responded with a status of 404 (Not Found)

Since there seems to be no automatich non-HTTP to HTTPS redirect, I have to manually prefix "https" in my browser's address bar.

My suggestion:

Please add an automatic redirect to HTTPS.

Document available refactors

There is no documentation available about what refactoring and fixits are supported by TypeScript.

Great note by the Abracadabra extension

Playground support compiler option --jsxFactory

As title

www.typescriptlang.org doc style problem

http://www.typescriptlang.org/docs/tutorial.html

It looks like this on

• macOS sierra
• RMBP 15 inch(2880 x 1800)
• Chrome 53
  

By guessing the class name you use col-md-2 & col-md-10, I believe it should look like

and safari is ok

I can not find a repo for the website, so I report this problem here.

Playground: code formmating broken with TS3.4+ readonly notation

Code:
Looks like the readonly modifier for arrays breaks code reformatting in the Playground.

// comment out to allow reformatting
const oops: readonly number[] = [1, 2, 3];
/*
SyntaxError: "',' expected. (2:22), parser-typescript.js
> 2 | const oops: readonly number[] = [1, 2, 3];
    |                      ^
*/

// Alt + Shift + F: IT DOES NOTHING!!!
const 
x 
= 
1;

Expected behavior:
Code reformats (so const x = 1; is moved to a single line)

Actual behavior:
Code does not reformat. A console error indicates that the readonly modifier is not expected.

Playground Link:
Playground Link

Related Issues:
microsoft/TypeScript#29435, introducing the readonly modifier for array types

Add support for different module types in the playground

See: https://github.com/orta/typescript-play/issues/3

[Feature request] TypeScript Playground presentation ability

I was thinking it would be nice to store a bunch of code examples for the TypeScript Playground.
I envision this allowing you to step through a list of code examples like a presentation.
This would be great when giving tutorials on how TypeScript compares with JavaScript.

ie
slide one:

slide two:

Request: Add support for running code in a new tab

I believe this was the old behavior for the playground. I think someone would need to create some kind of user settings and UI for this too.

Support type extraction from Deno-styled imports

E.g.

import { serve } from 'https://deno.land/[email protected]/http/server.ts';

Should know what shape serve is

Compiler API Examples don't work anymore

Before:

    const program = ts.createProgram([], {
        target: ts.ScriptTarget.ES5,
        module: ts.ModuleKind.CommonJS
      })

After:

    const program = ts.createProgram({
      rootNames: [],
      options: {
        target: ts.ScriptTarget.ES5,
        module: ts.ModuleKind.CommonJS
      }
    })

https://github.com/Microsoft/TypeScript/wiki/Using-the-Compiler-API

Parentheses causes TS Playground to crash

TypeScript Version: 3.5.1

Search Terms:

parentheses, max call stack size

Code

const x = (/*snip some parentheses*/(42)/*snip some parentheses*/);
const y : 41 = x;

I was curious if TS would optimize away extra parentheses when parsing and constructing its AST and whatnot.

Is this why @keithlayne hates unnecessary parentheses?

Expected behavior:

42 should not be assignable to 41

Actual behavior:

Playground Link: Playground

Related Issues:

Listing of community-contributed starter/boilerplate projects?

After struggling to configure a Typescript project which exports both a CommonJS and ES6 module (for tree-shaking with Rollup), I spent some time putting together a typescript-starter project with source-mapped test coverage, typedoc documentation generation, a performant watch task, etc.

Looking around, there are dozens of outdated and neglected starters/boilerplates available, but none seem to have gained enough traction to continue being updated when newer versions of Typescript or improved tooling becomes available. (E.g. many are still using tsd, which has been deprecated.)

Electron does really well (IMO) with promoting community-maintained tools and projects – have you all considered providing something similar on the Typescript website or README.md? It might really help the ecosystem to coalesce around and maintain a few strong options.

Suggestion:It will be good to open multi language of document and let us to translate it.

I want to translate some of the document to Chinese. But I cannot show it on the website.

Unnessassary horizental scroll on website on mobile

Galaxy S9, Android 8, Firefox.

Entire website other than the sticky menu bar is movable by horizontal scroll (right side). Not a website-brekaing issue but definitely an easily visible bug.

JSDoc comment types not working in Playground

I tried to use the JSDoc comment-style syntax in the Playground, but apparently it doesn't work:

http://www.typescriptlang.org/play/#src=%2F**%0D%0A%20*%20%40param%20%7Bstring%7D%20p1%20-%20A%20'rest'%20arg%20(array)%20of%20strings.%20(treated%20as%20'any')%0D%0A%20*%2F%0D%0Afunction%20fn9(p1)%20%7B%0D%0A%20%20return%20p1.join()%3B%0D%0A%7D%0D%0A%0D%0Afn9(5)

Is it disabled there?

Playground missing strictBindCallApply

Looks like the new Playground doesn't have the --strictBindCallApply compiler option available. It seems suboptimal that we can't do the equivalent of --strict in the Playground (and has caused a few issues when trying to reproduce issues or share code in Stack Overflow that rely on this functionality)

I guess I'm opening this here instead of at microsoft/TypeScript, or at agentcooper/typescript-play, but please tell me if this should be moved. Thanks!

Code

class Class {
  prop = "foo";
  method() {
    return this.prop;
  }
}

const instance = new Class();

const boundMethod = instance.method.bind(instance); // any
boundMethod - 7; // no error
const boundMethod2 = instance.method.bind<() => string>(instance); // error
// bind is not generic   ---------------> ~~~~~~~~~~~~

Expected behavior:
boundMethod should be strongly typed as () => string

Actual behavior:
boundMethod is any

Playground Link:
Playground Link

Related Issues:
https://github.com/orta/typescript-play/issues/11 microsoft/TypeScript#27028: introduction of --strictBindCallApply

Playground could have dts mode instead of the JS

New playground on typescriptlang site: Windows 10 users cannot see DOM output values, other than alert

When trying to write to the DOM, as for example, the Classes sample code, nothing happens when pressing Run.
However, it works when using iPad.
The old playground worked fine.
Please help.

JavaScript files in the playground don't show errors

Honestly not sure what's up with that, did a dive into it earlier but haven't figured - maybe it's in Monaco typescript?

Support using the target + lib options to resolve d.ts per playground session

I was trying to help someone with a problem using Object.entries but the playground didn't think it existed. The options panel is great, but doesn't offer a way to specify the lib option. This is a fairly troublesome issue when trying to help people with their modern, up-to-date code.

Perhaps a short-term easy fix would be to default to the latest libs?

Eventually, being able to specify libs (or even a full tsconfig.json as suggested in #4) would probably be best.

lib.d.ts doesn't include lib.iterator.d.ts probably?

https://www.typescriptlang.org/play/?downlevelIteration=true&target=1#code/DYUwLgBA2gdHAeBdCBeCAidQ

Could the playground have a mode for working on ambient declarations?

Ability to search in TypeScript documentation

Search Terms

documentation, search

Suggestion

Add the ability to search in TypeScrip documentation

Use Cases

When reading TypeScript 3.0 release notes I stumbled into "Rest parameters with tuple types". As a JS developer I don't know what tuple types are. I don't know when tuple types were added to TS and there is no way to search the documentation.

Examples

Search bar at the tof of the page.

Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript / JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. new expression-level syntax)

JSX doesn't work in playground

Which looks confusing for our samples.

http://www.typescriptlang.org/play/index.html?checkJs=true&allowJs=true&jsx=2#example/jsx

Can the playground support literate programming?

E.g. can you embed markdown content in-between sections of code. This is done really well in Swift playgrounds.

Playground should allow raw TSConfig.json input

Options drop-down is sort of hard-coded, and limited (see for example).

Is it possible to allow parameters in raw tsconfig JSON please?

Especially useful for experimenting, and trying error cases in full compiler then copy-pasting in playground.

https://github.com/orta/typescript-play/issues/4

Documentation Temnplates lose highlights when viewing individual templates

TypeScript Version: 2.6.0-dev.201xxxxx

Expected behavior:
When I visit documentation for templates the list of templates are shown and on the side bar templates is highlighted. I expect that when I visit each template the menu should keep templates as highlighted as i am within that section. For example visiting this page should not remove highlight from templates.
I expect that Templates menu would stay highlighted as long as I am visiting pages under Templates section.

Actual behavior:
When visiting template list page menu indicates that I am on template page where as on visiting any sub pages it keeps the "Declaration Files" section open but removes highlight from Templates section which makes it unclear which section this file belongs to. User can see from URL that this file belongs within template section as a work around. Sharing this link with others also cause confusion as they dont know which section to go to see more templates.

Playground url could encode user's selection

So that when you want someone to look somewhere it can be highlighted

Documentation page doesn't seem to work

Documentation page doesn't seem to work.
https://www.typescriptlang.org/docs/home.html throws The resource you are looking for has been removed, had its name changed, or is temporarily unavailable..

Automated accessibility tooling

Overviews:

• https://docs.microsoft.com/en-us/microsoft-edge/accessibility/test
• https://aka.ms/accessibilityinsights
• https://developers.google.com/web/fundamentals/accessibility/how-to-review

Tools which are useful here:

• https://github.com/microsoft/webhint-hints-microsoft
• accessibility insights
• eslint-plugin-jsx-a11y
• https://webhint.io/
• gatsby-plugin-react-axe - react-axe

Running Lighthouse?

• [https://offbyone.tech/lighthouse-circleci/](via jest)
• https://www.matuzo.at/blog/building-the-most-inaccessible-site-possible-with-a-perfect-lighthouse-score/
• as a service

Update Playground Examples

The TypeScript Playground examples are... not great. We deserve a new set.

General principles

• Don't lean on classes
• Show off type inference where possible - minimal annotations
• Emphasize working with JavaScript
• Show both error-finding and good intellisense

Please Suggest More!

---

Basic Types & Inference

const array = ["red", "green", "blue", "yellow"];
array.forEach(color => {
  // TypeScript knows 'color' is a string and warns on the incorrect method name
  console.log(color.toUppercase());

  // Try typing 'color.' on this line to see members of string
  color
});

// TypeScript knows s has one of two string values.
// This can detect some different errors
const s = Math.random() > 0.5 ? "aaa" : "bbb";
// ... like the spelling error here
if (s === "aa") {
 // oops
}
// ... and the logic error here!
if (s === "aaa" && s === "bbb") {
  // oops
}

Functions

function check(s: string) {
  return s.length > 3;
}

// TypeScript warns if we get the argument count wrong
check();
// Or if the argument type is wrong
check(10);

// The return type of the function is inferred,
// so errors like this are automatically detected
if (check("hi") === "world") {
  // Never true because 'world' isn't a boolean
}

Union Types

// TypeScript can work with objects of mixed types
const items = ["red", 10, 15, "blue"];
for (const i of items) {
  if (typeof i === "string") {
    // TypeScript knows 'i' is 'string' here
    console.log(i.toUpperCase());
  } else {
    // 'i' is of type 'number' here
    console.log(i * 2);
  }
}

Generics

ES6 Classes

What else?

Export to Code Sandbox

Notes:

• https://codesandbox.io/docs/importing#define-api

• Can re-implement https://www.unpkg.com/[email protected]/lib/api/define.js with our own string lzer probably

• Code to do it:

import { getParameters } from 'codesandbox/lib/api/define';

const parameters = getParameters({
  files: {
    'main.ts': {
      content: "console.log('hello')",
    },
    'package.json': {
      name: "TypeScript Playground Export rand(1-50k)",
      description: "[]",
      keywords: "typescript",
      content: { dependencies: { typescript: "*", "ts-node": "*" } },
    },
  },
});

const url = `https://codesandbox.io/api/v1/sandboxes/define?parameters=${parameters}`;

No way to tab to the gray buttons

Examples, Options, Run, etc. are created as p tags in the DOM. This means they don't have tab focus when the user is pressing tab around the site. This is a particularly bad problem for users without a mouse, such as accessibility users, and for users who prefer to navigate quickly using the keyboard.

Recommended solution: switch them to <button type="button">.

Feature request: per-page TOC for website's documentation

Search Terms

handbook, typescriptlang, website

Suggestion

The documentation on the website (example) if not user friendly at all.

There is a TOC on the left for all the pages. But there is no TOC per-page.

Scroll down that example I linked to - see how hard it is to find any info? There needs to be a TOC at the top of the page, and even better, a scrolling TOC on the right that shows where you are right now.

The documentation is of a high quality, but accessing it is a chore.

typescriptlang.org does not support https without www

Expected: site should default to https.

Actual: does not load.

HSTS for typescriptlang.org

www.typescriptlang.org supports HTTPS!

It would be pretty snazzy if typescriptlang.org went HTTPS only, and preloaded [HSTS](https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security:
https://hstspreload.org/?domain=typescriptlang.org

This would entail:

• Fixing https://typescriptlang.org (HTTPS, no www) so that it doesn't hang.
• Sending HSTS headers from typescriptlang.org and www.typescriptlang.org.
• Submitting typescriptlang.org to the HSTS preload list.

I maintained the HSTS preload list in the past, so I'm happy to answer questions about recommended configurations and what they mean!

Thanks for any consideration,
»Lucas

Playground option to choose among recent, current, and nightly builds

It would be helpful to check specific cases if the playground allowed us to play around in different versions of typescript. Can that please be an option?

Documentation links are hard to spot

On the TypeScript website, links within the page content are hard to spot. There are two issues:

• Normal links are different from paragraph text in color only, with a contrast ratio to surrounding text that is too low (text: #242424, link: #265988, contrast ratio: 2.11:1).
• Links on code-style text are visually identical to code-style text without links

Example:

https://www.typescriptlang.org/docs/handbook/declaration-files/library-structures.html

Search Terms:

Website links, documentation links, documentation code link, accessibility

Expected behavior:

It should be possible to visually scan a documentation page and identify what is a link.

Actual behavior:

Links on paragraph text have a very low contrast ratio that makes them hard to spot. Links on code are impossible to spot, and it's very frustrating to have to hover all the inline snippets or try to guess which ones are links.

Related Issues: Couldn't find any.

---

I can see a few solutions to this:

• Style links based on something else than color. The established accessibility best practice is to use an underline.
• Pick a color for links that has high-enough contrast to surrounding text.
• For code links, display them with the link color rather than the code color #bf414a.

Relevant resources:

• https://webaim.org/techniques/hypertext/link_text#appearance
• WCAG 2.0 F73: Failure of Success Criterion 1.4.1 due to creating links that are not visually evident without color vision
• WCAG 2.0 G183: Using a contrast ratio of 3:1 with surrounding text and providing additional visual cues on focus for links or controls where color alone is used to identify them

typescriptlang.org: using the Monaco editor doesn't dismiss the cookie banner

Search Terms: typescriptlang org cookie banner mscc

Steps to reproduce:

1. Open typescriptlang.org/play in a new window
2. Type anything and/or click around into the source editor
3. Observe that the "This site uses cookies ..." banner remains

Microsoft's CELA & cookie teams say the banner can only be dismissed once the user has demonstrated intent to use the webpage. That includes interacting with interactive elements on the page, such as playable widgets.

[Suggestion] Improve the docs for mixins

The official documentation contains very old docs for mixins: https://www.typescriptlang.org/docs/handbook/mixins.html

Since then, the mixin pattern has evolved:
https://mariusschulz.com/blog/typescript-2-2-mixin-classes
https://www.bryntum.com/blog/the-mixin-pattern-in-typescript-all-you-need-to-know/

I'm volunteering to update documentation with the "officially blessed" content from the 2 links above.

The problem with the approach from the handbook, is that it uses ad-hoc copying of properties from one prototype to another and mixins will not compose well, because one can't use super in methods. Such copying also feels not type-safe. The new approach is free from these drawbacks.

If someone can point me to the canonical source of the mixins docs page (source file in some repo or a wiki page?) I'm volunteering to update the docs with the "modern" mixin pattern.