Here's a quick `.cursor/rules` addition you can make for handling return types in TypeScript.

````md
# Return Types

When declaring functions on the top-level of a module,
declare their return types. This will help future AI
assistants understand the function's purpose.

```ts
const myFunc = (): string => {
  return "hello";
};
```

One exception to this is components which return JSX.
No need to declare the return type of a component,
as it is always JSX.

```tsx
const MyComponent = () => {
  return <div>Hello</div>;
};
```
````

Should You Declare Return Types?

Since the AI-assisted development era began, I have had dozens and dozens of requests to share my `.cursor/rules` for writing TypeScript code.

I was hoping to rely on community resources for this. There are dozens of directories springing up to document different folks' Cursor rules.

But my brief explorations into these community directories have been disappointing. The rules that are there are low-quality, underwritten, low on code examples, and not widely applicable.

So I'm here to give you my Cursor rules, such as they are. I don't think they're perfect. They are not as battle-tested as I would like.

But I do think that we, as a community, need to start coming to some consensus as to what makes a good cursor rule. So I'm hoping that this article will kick off that discussion.

## The Rules

I've designed these rules so that they don't focus on specific frameworks or libraries. Instead, they are just focused on the TypeScript language.

This means that anywhere you use TypeScript, these rules should benefit you.

They fall into a few different buckets:

- **Language features**: preferring `as const` to enums, preferring `import type` to `import { type }`, `readonly` properties
- **Documentation**: prompting the LLM to use JSDoc comments better
- **Code Structure**: preferring `Result` over `try/catch`, allowing `any` inside generic functions, discriminated unions, return types on functions
- **Teaching The LLM About TypeScript**: helping it understand `noUncheckedIndexedAccess`
- **Library usage**: preferring to install packages via CLI instead of manually editing `package.json`

You can [download them here](https://res.cloudinary.com/total-typescript/raw/upload/v1745426569/articles/cursor-rules-for-better-ai-development/cursor-rules.zip).

## What makes a good Cursor rule?

There are two kinds of cursor rules that come to mind.

### Workspace Rules

The first kind of cursor rules are workspace rules. These are rules which are checked into Git and versioned alongside your code.

This type of cursor rule lets you do a few things:

- Tell the AI which version of packages you are using
- Give the AI an idea of the structure of your project
- Provide framework and library-specific advice

### Global Rules

The second kind of cursor rule are rules which are tailored for you.

These are rules which are not checked into Git, but live in your IDE.

They are rules which are specific to your coding style, your preferences and your workflow. They let you:

- Customize the behavior of the AI by giving it role-based prompts: "Think deeply about each problem", "use simple solutions"
- Add workflow based commands: "commit your work after each task

Learn TypeScript cursor-rules for AI development. Covers best practices, JSDoc, structure. Differentiates workspace & global rules for better AI coding

Finding existing community .cursor/rules for TypeScript lacking, I'm sharing my own set to hopefully kickstart a discussion on what makes effective AI coding guidance. These rules focus purely on TypeScript language features, documentation, structure (like Result types), teaching the AI specific nuances (like noUncheckedIndexedAccess), and practical habits, rather than specific frameworks. I also distinguish between shareable, project-specific Workspace Rules (versioned in Git) and personalized Global Rules (living in your IDE) to tailor the AI to your individual style and workflow. You can download my current ruleset using the link in the original post.

Cursor Rules for Better AI Development

Today, [TypeScript announced](https://devblogs.microsoft.com/typescript/typescript-native-port/) a full rewrite of TypeScript in Go. In testing, this rewrite has achieved a 10x speedup in some repositories - and up to 15x in others.

This speedup will affect every part of the TypeScript ecosystem: from running `tsc` via CLI to the performance of hovers and errors in your IDE. Once released, you'll be able to adopt the new version of TypeScript without changing a single line of code.

Improved performance has been the community's most-requested feature for years. [Several attempts have been made](https://www.totaltypescript.com/rewriting-typescript-in-rust) to rewrite TypeScript in a faster language, but none have succeeded.

On Friday (9AM PT) I'll be interviewing Anders Hejlsberg, the lead architect of TypeScript, to discuss the rewrite. Join in on [YouTube](https://www.youtube.com/live/NrEW7F2WCNA) for the live stream.

## How will this affect me?

Once released, the Go rewrite will improve the DX for every TypeScript developer. Let's break each element down:

### IDE

Your IDE experience will become 10x faster. This means:

- Loading large TypeScript codebases
- Hovers
- Errors
- Go-to-definition
- Rename symbol

...and all other TypeScript features will be 10x faster.

This will especially affect large monorepos, where the TypeScript language server can be painfully slow.

This won't just be in VSCode (or VSCode forks like Cursor and Windsurf). Any code editor that uses the TypeScript language server will benefit.

### CLI

The TypeScript compiler (`tsc`) will be 10x faster. This means faster type-checking locally, and faster builds.

It will also be transformative for CI. Transpiling TypeScript files into JavaScript has gotten extraordinarily fast with tools like `esbuild` (written Go) and `swc` (written in Rust). But type-checking has remained slow.

Now, the slowest part of your CI will become much faster - speeding up builds everywhere.

### Will I have to change my code?

No, your code will stay exactly the same.

## When will it be ready?

The release has been promised for TypeScript 7.0. TypeScript doesn't follow semantic versioning - releases simply count up from 1.8, 1.9, 2.0 - and they release a new version every 3 months or so. We're on version 5.8 now - so by the current cadence 7.0 will be around 33 months away.

However, it seems more likely they'll simply release it when it's ready. My hunch would be that a beta will be ready by November 2025.

## How can I try it out?

Check out the new [typescript-go](https://github.com/microsoft/typescript-go) repo for instructions.

## Will development pause on the current TypeScript codebase?

No - new features will continue to be added to the JavaScript version of the codebase as the Go version is being developed.

Some of the TypeScript team will work on the codebase full-time. Some will continue work on the JavaScript version.

## Why not Rust?

The TypeScript team posted about their reasoning for choosing Go in a [GitHub discussion](https://github.com/microsoft/typescript-go/discussions/411).

It seemed to be the best choice for several key reasons. Far and away the most important reason was its structural similarity to the current JavaScript implementation. Go's programming patterns closely resemble TypeScript's existing code structure.

Here's a still from the Anders Hejlsberg presentation. TypeScript is on the right, Go on the left.

![A still showing a Go and TypeScript codebase looking very similar](http://res.cloudinary.com/total-typescript/image/upload/v1741704753/posts/post_k3ou7/tmrmx6qajkdw3kjtq8ty.png)

This means that contributors familiar with the existing codebase will be able to navigate the codebase easier. This is crucial since both codebases will be maintained simultaneously for some time.

So - nothing against Rust. Go seemed to fit the bill better.

## Why not speed up the JavaScript code?

To speed up a TypeScript, you need a language with multi-threading support. JavaScript can only really work on one core at a time. It has some upcoming features (like [Shared Structs](https://github.com/tc39/proposal-structs)) which can be shared across threads, but they're not ready yet.

Languages like Go and Rust have multi-threading support built-in, which means they can use multiple CPU cores to parallelize as much work as possible. This is why they're so much faster.


TypeScript announced a full rewrite of TypeScript in Go. In testing, this rewrite has achieved a 10x speedup in some repositories - and up to 15x in others.

TypeScript Announces Go Rewrite, Achieves 10x Speedup

In `TypeScript` 5.8, a new flag is dropping. It's called `erasableSyntaxOnly`.

It disables a bunch of features that I don't think should ever have been part of `TypeScript`.

Let's talk about it.

## What Does `erasableSyntaxOnly` Do?

`erasableSyntaxOnly` marks enums, namespaces and class parameter properties as errors. These pieces of syntax are not considered erasable.

So the code below would result in three errors:

```ts
// Error! Not allowed
enum Example {
  foo,
}

// Error! Not allowed
namespace OhNo {
  export const foo = 1;
}

class X {
  // Error! Not allowed
  constructor(private foo: string) {}
}
```

## What Does 'erasable' Mean?

'Erasable' syntax means that the syntax can be deleted without the runtime behaviour being affected.

Normal type annotations are erasable. Removing the type annotation below results in legal JavaScript:

```ts
const foo: string = 'foo';

const foo         = 'foo';
```

Same with function parameters:

```ts
const func = (a: string) => {}

const func = (a        ) => {}
```

Enums, namespaces and class parameter properties do not obey this rule. This makes it much harder for bundlers to work with them.

## Why Is `erasableSyntaxOnly` Being Added?

Node's recent [TypeScript support](https://www.totaltypescript.com/typescript-is-coming-to-node-23), by default, only supports erasable syntax.

So turning on `erasableSyntaxOnly` is a really good option there.

But I think the TypeScript team is looking toward a future where these syntaxes will no longer be used.

There are several proposals floating to add types to JavaScript. One of the most popular is [types as comments](https://tc39.es/proposal-type-annotations/), which would allow JavaScript to treat types in code as ignorable at runtime.

This would mean that the following code would be valid JavaScript:

```ts twoslash
const x: number = 12;

const func = (a: number, b: number) => a + b;
```

This would be an enormous boon to the ecosystem, and bring us closer to TypeScript in the browser.

But the issue is that this only works with erasable syntax. Anything that requires a more complex transformation, like enums or namespaces, won't work in this model.

## What about import aliases?

Import aliases (via the [`paths`](https://www.typescriptlang.org/tsconfig/#paths) config option) are a popular way of handling imports. However, they won't work with `erasableSyntaxOnly`.

The recommended solution is to rely on the non-TypeScript method for handling this: [`package.json#imports`](https://nodejs.org/api/packages.html#imports). TypeScript and Node handle this out of the box.

## When Will This Land?

This is slated to launch in TypeScript 5.8, which is due pretty soon.

You can try it right now on the [TypeScript playground](https://www.typescriptlang.org/play/?erasableSyntaxOnly=true&ts=5.8.0-dev.20250124#code/KYOwrgtgBAogHgQwgBwDbCgbwFBT1AdwHsDsBfIA). Enjoy!


TypeScript 5.8's new erasableSyntaxOnly flag enforces pure type annotations by disabling enums, namespaces, and parameter properties.

TypeScript 5.8 Ships --erasableSyntaxOnly To Disable Enums

Node 23 will soon be able to run TypeScript files without any extra configuration.

[Marco Ippolito](https://x.com/satanacchio), who has been driving TypeScript support in Node for the last year, landed a [PR](https://github.com/nodejs/node/pull/56350) unflagging `--experimental-strip-types` in Node 23.

Practically, this means a few things:

- You can create an `index.ts` file containing TS syntax, like type annotations.
- You can run `node index.ts` with no further flags
- Node will strip out the types using a version of `swc`, then run the resulting code.

Let's treat this article as a FAQ:

## How Can I Try It?

It's now available in the Node Nightly version, as mentioned by [Marco](https://x.com/satanacchio/status/1872574795390530000). In a few days it'll likely get a release in Node 23.

UPDATE: Looks like it's coming to [23.6.0](https://github.com/nodejs/node/pull/56450).

## Will Node Typecheck My Files?

No. Node will not typecheck your files when it runs them. This is a good thing - it means that typechecking can run in a separate process to running your app.

You'll need to run `tsc --watch` locally to typecheck your app as you work.

## What Should Be In My `tsconfig.json`?

This is a tailored version of my [TSConfig Cheat Sheet](https://www.totaltypescript.com/tsconfig-cheat-sheet).

```json
{
  "compilerOptions": {
    /* Base Options: */
    "esModuleInterop": true,
    "skipLibCheck": true,
    "target": "es2022",
    "allowJs": true,
    "resolveJsonModule": true,
    "moduleDetection": "force",
    "isolatedModules": true,
    "verbatimModuleSyntax": true,
    /* Strictness */
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitOverride": true,
    /* Node Stuff */
    "allowImportingTsExtensions": true,
		"rewriteRelativeImportExtensions": true,
    "module": "NodeNext",
    "noEmit": true,
    /* If your code doesn't run in the DOM: */
    "lib": [
      "es2022"
    ],
  }
}
```

This will likely change in TS 5.8, where the TypeScript team are planning to ship a compatibility flag. Not sure what's in it yet, but it'll make interop with Node's TS support easier.


## Are Enums and Namespaces Supported?

Enums and namespaces are not supported by default. Check out the other features which are not supported [here](https://nodejs.org/api/typescript.html#type-stripping). If you want support for other TS features, you can add `--experimental-transform-types` to make it work.

I'm personally not too sad about this - especially about the [enums](https://www.totaltypescript.com/why-i-dont-like-typescript-enums).

Note that runtime namespaces are not supported, but type-only namespaces (using `declare namespace`) _are_ supported. This is nice - I like type-only namespaces.


## Do I Need To Transpile To JavaScript For Production?

### Node apps

If you're deploying your code to a serverless platform, yes. Transpiling and minifying your code will be key to getting a good cold start.

If you're deploying to a place where cold starts matter less, then probably not! There will be a small cost when the app initially loads your TypeScript (and I do mean small), but once the process is running it's unlikely to cause slowdowns.

One possible wrinkle is if your code dynamically loads other TypeScript files during its processing. I could see that resulting in a little extra slowdown - so tread carefully.

### Libraries

Yes, you still need to transpile your TypeScript to JavaScript before shipping it to NPM. There are two reasons for this:

- So JavaScript users can still consume your library
- TypeScript works faster when consuming declaration files (`.d.ts` files), so not shipping them means you're making your consumers' TS experience slower.

### Monorepos

If you're creating a library in a monorepo, for only that monorepo to consume, I still recommend transpiling your TypeScript files to JavaScript.

The reason is the same as for libraries - the more `.d.ts` files you have in your monorepo, the faster your TS experience will be.

## Will This Come To Previous Versions Of Node?

Yes, TypeScript support will be coming to Node 22, but not Node 20.

[Marco](https://x.com/satanacchio/status/1872426617039114243) mentioned this on X.

TypeScript is coming to Node 23. Let's break down what that means.

Node.js Now Supports TypeScript By Default

Let's talk about another crazy TypeScript trick: `Array[number]`.

```ts twoslash
const roles = ["admin", "editor", "contributor"] as const;

type RolesAsType = typeof roles;

type Role = RolesAsType[number];
//   ^?
```

It looks like absolute insanity.

But I promise by the end of this email, you'll know how it works.

## Extracting Types From Arrays

Let's start with a slightly simpler example.

First, we'll define an array of some fixture data we might use in some tests.

```ts twoslash
const possibleResponses = [
  {
    status: 200,
    body: "Hello, world!",
  },
  {
    status: 404,
    body: "Not found",
  },
  {
    status: 500,
    body: "Internal server error",
  },
];
```

We can use `typeof` on `possibleResponses` to extract its type.

We can see that it is an array of objects with a `status` and `body` property.

But what if we want to remove the 'array' part of the type and just get to the object inside?

```ts twoslash
const possibleResponses = [
  {
    status: 200,
    body: "Hello, world!",
  },
  {
    status: 404,
    body: "Not found",
  },
  {
    status: 500,
    body: "Internal server error",
  },
];
// ---cut---
type PossibleResponses = typeof possibleResponses;
//   ^?
```

We can use this arcane-looking trick, `Array[number]`, to extract the type of the array.

```ts twoslash
const possibleResponses = [
  {
    status: 200,
    body: "Hello, world!",
  },
  {
    status: 404,
    body: "Not found",
  },
  {
    status: 500,
    body: "Internal server error",
  },
];
type PossibleResponses = typeof possibleResponses;

// ---cut---
type PossibleResponse = PossibleResponses[number];
//   ^?
```

Why does this work? What even is this syntax?

## Indexed Access Types

Well, the syntax is an indexed access type. It's the way to access a property on a type.

A simpler version would be to grab a property from an object:

```ts twoslash
type NavbarProps = {
  onChange: () => void;
};

type OnChangeType = NavbarProps["onChange"];
//   ^?
```

By passing `number` to the indexed access type, we're saying "give me all the properties of the object that are accessed with numeric keys".

To demonstrate this, we can create an object with string keys, but a numeric index signature:

```ts twoslash
type ExampleObj = {
  // String keys
  stringKey1: "string-key";
  stringKey2: "string-key";

  // Numeric index signature
  [key: number]: "number-key";
};
```

We can then use `ExampleObj[number]` to extract only the numeric values from the object.

```ts twoslash
type ExampleObj = {
  // String keys
  stringKey1: "string-key";
  stringKey2: "string-key";

  // Numeric index signature
  [key: number]: "number-key";
};

type NumericValuesOnly = ExampleObj[number];
//   ^?
```

## What's The Point?

Keen observers might be looking at this with scepticism. Is this trick really useful?

Surely, you would just create the type _first_, then use it in your application.

No need to extract it from an array.

```ts twoslash
type Response = {
  status: number;
  body: string;
};

const possibleResponses: Response[] = [
  {
    status: 200,
    body: "Hello, world!",
  },
  {
    status: 404,
    body: "Not found",
  },
  {
    status: 500,
    body: "Internal server error",
  },
];
```

Well, this trick comes into its own in a few places.

It goes without saying that it's useful in library code.

But it's also great when you're building your own enums from arrays, like in the first example.

```ts twoslash
const roles = ["admin", "editor", "contributor"] as const;

type RolesAsType = typeof roles;

type Role = RolesAsType[number];
//   ^?
```

By the way, this example works because `roles` is marked `as const`, which makes TypeScript infer the literal values of the array.

Without it, TypeScript would infer the type as `string[]`:

```ts twoslash
const roles = ["admin", "editor", "contributor"];

type RolesAsType = typeof roles;

type Role = RolesAsType[number];
//   ^?
```

Deriving types from values is an extremely powerful concept - so much so that I wrote an [entire chapter of my book](https://www.totaltypescript.com/books/total-typescript-essentials/deriving-types) on it.

So, that's `Array[number]` in TypeScript. It extracts all the numeric keys from an object.

In the case of an array, that means it extracts the type of the array member.


Learn how to extract the type of an array element in TypeScript using the powerful `Array[number]` trick.

This Crazy Syntax Lets You Get An Array Element's Type

Learn how to publish a package to npm with a complete setup including, TypeScript, Prettier, Vitest, GitHub Actions, and versioning with Changesets.