TypeScript

Greenwood provides built-in support for TypeScript, either through type-stripping (default behavior) or with the ability to fallback to using the TypeScript compiler if you're leveraging certain transformation based TypeScript features (like enums and namespaces (opens in a new window)) or JavaScript syntax like Decorators. If you need these additional capabilities, you can set the useTsc option in your Greenwood configuration file.

You can read this guide (opens in a new window) to learn more about running TypeScript with NodeJS, including the --experimental-transform-types (opens in a new window) flag. You can see an example Greenwood TypeScript repo here (opens in a new window).

Setup

The below steps will help you get up and running with TypeScript in your Greenwood project, and are the same settings (opens in a new window) you'll get running Greenwood's init package with TypeScript enabled. The general recommendation is to use type-stripping during development for faster live reload, and then run TypeScript during CI (e.g. GitHub Actions) to check and enforce all types, e.g. tsc --project tsconfig.json.

You will need to use Node >= 22.6.0 and set the --experimental-strip-types flag
Install TypeScript into your project, e.g. npm i typescript --save-dev
Create a tsconfig.json file at the root of your project with the below minimum configuration settings.
We also recommend additional configurations like verbatimModuleSyntax (opens in a new window) and erasableSyntaxOnly setting (opens in a new window)

{
  "compilerOptions": {
    // minimum required configuration
    "target": "es2020", // needs to be at least >= es2015 for `class` support
    "module": "preserve",
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "noEmit": true,

    // additional recommended configuration
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "verbatimModuleSyntax": true,
    "erasableSyntaxOnly": true,
  },

  "exclude": ["./public/", "./greenwood/", "node_modules"],
}

If you're feeling adventurous, you can use >=23.x and omit the --experimental-strip-types flag. Keep an eye on this PR (opens in a new window) for when unflagged type-stripping support may come to Node LTS 22.x. 👀

Types

Configuration

In addition to being able to author your components, SSR pages, and API routes in TypeScript, you can also author your configuration file (and plugins) in TypeScript by using a greenwood.config.ts file.

import type { Config } from '@greenwood/cli';

const config: Config = {
  // ...
}

export default config;

We recommend putting the type on the outside of the braces to avoid inadvertent bundling (opens in a new window) of the package your importing from.

See our reference docs on Greenwood's available types for more information on authoring with TypeScript.

Import Attributes

Currently TypeScript only supports types for standard JSON Import Attributes (opens in a new window) as of TypeScript 5.4. There is an open issue tracking CSS Module Scripts support (opens in a new window), so in the meantime you can use the below snippet as a reference for providing this type for yourself in your own project.

declare module "*.css" {
  const sheet: CSSStyleSheet;

  export default sheet;
}

Edit on GitHub

Introduction

Pages

Resources

Plugins

Content As Data

Reference