Typescript support for External Source Plugins

[lschierer]

Type of Change

New Feature

Summary

Please support using TypeScript to write an External Source Plugin

Details

I attempted to follow https://www.greenwoodjs.io/plugins/source/ changing the .js extension out for .ts and get an ERR_UNKNOWN_FILE_EXTENSION that persists even after I was assisted in solving these errors for other sections of my configuration here.

I suspect that its actually possible to do this, but that it would be (currently) a multi-step process, where I'd need to transpile the plugin to javascript to then be able to run the greenwood develop or build commands. This request is to support, and document, a configuration that will consolidate that into a single command line that could be included as the develop script in a package.json file.

I further suspect that this is related to #1250 where in the comments I requested support for the main configuration file to be supported as a typescript file. My intuition is that if you solved that, this would be mostly solved as well.

[thescientist13]

I further suspect that this is related to #1250 where in the comments I requested support for the main configuration file to be supported as a typescript file. My intuition is that if you solved that, this would be mostly solved as well.

Yeah, pretty much. Right now the TypeScript plugin is only geared towards transforming "web" code, e.g. anything in your src/ directory, but not really anything else.

Let me align this with #1250 though since I think this would be something we would apply to all plugins at large. My guess is that this would likely try and tackle this in two phases:

1. Support exposing JS Docs style types (typing support for public capabilities of Greenwood #1250)
2. Have Greenwood support TypeScript files first party for its APIs (would probably re-purpose this issue for that effort)

I've also been experimenting with Bun and Deno and they are working pretty well out of the box with some Greenwood demo apps as part of initial testing, and so now with NodeJS also supporting TS, I may even considering moving TS support right into Greenwood itself, probably with a flag though. We shall see!

[thescientist13]

First Party TypeScript Support

So I had some time to play around with what first party TypeScript support might look like in Greenwood, and I think there might be a good path forward here, in particular now that NodeJS provides built-in support for type stripping (and some transformations). With this, a lot of the transformation work can be handled for us for free from the runtime itself. (and would also apply to Deno / Bun if and when we get to them!)

$ NODE_OPTIONS='--experimental-strip-types' greenwood <command>

Here's a good blog post on the feature and how it works under the hood.

NodeJS Support

As far as NodeJS support goes, it breaks downs like so:

• v22.6.0 (LTS) - --experimental-strip-types flag was added
• v22.7.0 (LTS) - --experimental-transform-type flag was added
• v23.0.0 (Non-LTS) - --experimental-strip-types unflagged

The recommended compiler config is:

{
  "compilerOptions": {
    "target": "esnext",
    "module": "nodenext",
    "allowImportingTsExtensions": true,
    "rewriteRelativeImportExtensions": true,
    "verbatimModuleSyntax": true,
    "checkJs": true,
    "allowJs": true,
    "noEmit": true,
    "skipLibCheck": true,
  }
}

We might also want to recommend TypeScript >=5.8 with erasableSyntaxOnly.

One important point the docs allude to is that it might be worth supporting a contingency wherein if a user wants full TypeScript support, then Greenwood might want to enable falling back to tsc itself, after the user has installed it.

Example:

// greenwood.config.ts
export default {
  // would process using tsc instead of amaro
  // and kick in for SSR pages and API routes
  useTsc: true|false
}

Configuration / Plugins

This one is pretty easy, we would just have to also check for a greenwood.config.ts file and with that, we should also get TS based plugins for free.

// greenwood.config.ts
import { customExternalSourcePlugin } from "./external-content-source-plugin.ts";

const port: number = 8181;

export default {
  devServer: {
    port
  },
  port,
  plugins: [
    customExternalSourcePlugin()
  ]
}

// external-content-source-plugin.ts
export const customExternalSourcePlugin = () => {
  return {
    type: "source",
    name: "source-plugin-external-page",
    provider: () => {
      return async function () {
        return [{
          title: 'My custom external page',
          body: '<h1>My custom external page</h1>',
          route: '/external/',
          label: 'External',
          data: []
        }];
      }
    },
  };
};

SSR Pages / API Routes

Enabling SSR pages (e.g. src/pages/index.ts) and API routes (e.g. src/pages/api/greeting.ts) would be pretty similar to enabling TS based configuration / plugisn; basically just allowing .ts as an extension in a couple places in Greenwood's graph lifecycle and during Rollup bundling:

• SSR pages - https://github.com/ProjectEvergreen/greenwood/blob/v0.31.1/packages/cli/src/lifecycles/graph.js#L92
• API routes - https://github.com/ProjectEvergreen/greenwood/blob/v0.31.1/packages/cli/src/lifecycles/graph.js#L100
• Bundling - https://github.com/ProjectEvergreen/greenwood/blob/v0.31.1/packages/cli/src/config/rollup.config.js#L340

Browser Scripts

However, this still leaves client / browser side code (e.g. <script> tags) as an outlier as obviously the browser does not support a way to handle TypeScript and all the imports happen in the browser, so we still at minimum need some transformation logic for these use cases. (unless there was actually a way to use import but to only get text contents, like it was fs)

This means Greenwood would have to at least pull in a dependency for this use case to do the transformations, and thus would have an internal "TypeScript" plugin. Luckily, we would at least have access to the same logic Node itself uses (amaro), which can be overridden through the resolutions / overrides feature of any modern package manager.

TL;DR

So in summary, the status of things seems pretty good and straight-forward, all things considered:

• Config / Plugins - ✅
• SSR Pages - ✅
• API Routes - ✅
• <script> - ⚠️

The scope required of this feature would breakdown as follows:

1. Deprecate the TypeScript plugin and bring its logic into Greenwood as first party (but needing / using amaro for <script> tags handling)
   • servePage option would just work automatically now
   • extendConfig option would no longer be applicable, but you can of course just copy paste from the website where we will have a recommended tsconfig.json (which will be the default)
2. Enable typescript first party via NodeJS + --experimental-strip-types (and make sure we're enabling anywhere we're specifically hardcoding checks for .js files / URLs, hot reloading, etc)
3. Organize all TypeScript related documentation on the website:
   • /docs/resources/typescript (how to use TypeScript with Greenwood, configuration recommendations, etc)
   • /docs/reference/types (just the types we export, and JS Docs)
   • have any relevant docs point back to these (e.g. config / plugin docs)
   • redirect /docs/plugins/typescript -> /docs/resources/typescript
4. Enable fallback / custom tsc configuration option
   • for examples, Amaro (and Bun) do not support standard decorators - [DEMO] Bun thescientist13/greenwood-lit-ssr#31

In general, since the work on the Greenwood is pretty minimal, and we are seeing validation even from the runtime itself, and given how foundational and useful TypeScript is to web dev now, and that we're basically able to externalize all the configuration, dependency management, and most of the transformations, it seems pretty low risk / effort to bring it into core. Additionally, I think the chance to consolidate all usage documentation into one place and not have to juggle between too many choices for users (if you you're using it like this do that, but if in this case, do this, otherwise if you're using it like this, do this...)

Please let me know if I have overlooked any particular surface areas of Greenwood in this analysis.

---

I've moved this to a discussion for now and then assuming all these pieces pan out from folks following along and the rest of the Greenwood team are on-board with the plan, I'll create a dedicated issue for introducing "first party" TypeScript support into Greenwood, which I think would then probably just invalidate #1327 and #658.

[lschierer]

This would be awesome!!

[thescientist13]

OK, had a chance to discuss with the team, and everyone is supportive here, so created a tracking issue for built-in TypeScript support for Greenwood - #1424.

Should be able to get to this in the next week and have this queued up for v0.32.0-alpha.1 which I hope to be able to cut next weekend. Please follow along with that issue and I will post in the Discord when the alpha release are available for testing / feedback. 👍