[router] move typed-routes logic into expo-router

[marklawlor]

Why

Expo Router's typed routes are not very maintainable. They are a separate set of types that need to be constantly manually kept in sync. This PR is a proposal to move the logic of typed routes into expo-router and simply have the @expo/cli clone a file.

How

First lets explain how typed routes work. TypeScript's types are like a stack. The value of a type is the first value that typescript resolves. You can override a modules types by providing your own declare module <package> definitions. However those types will have dependencies, and those values will be resolved relative to itself. So you cannot override the dependencies of types, you need to override the exported values. This is why we were keeping types manually sync'd.

This proposal moves all the types into expo-router and have the @expo/cli simply copy the type definitions and modify some lines. This way the types generated by @expo/cli are exactly the same as Expo Router.

To make this process easy, we need to centralise all expo-router types used by typed routes into a single file. I've created an ambient namespace ExpoRouter that is globally accessible in the expo-router package. Its quite easy to transform a namespace to a module as they share the same syntax.

expo/packages/@expo/cli/src/start/server/type-generation/routes.ts

Lines 103 to 124 in 2fbcc2d

	try {
	let types = await fs.readFile(path.resolve('expo-router/typed-routes.d.ts'), 'utf-8');
	types = types
	// Swap from being a namespace to a module
	.replace('declare namespace ExpoRouter {', `declare module "expo-router" {`)
	// Add the route values
	.replace(
	'type StaticRoutes = string;',
	`type StaticRoutes = ${setToUnionType(staticRoutes)};`
	)
	.replace(
	'type DynamicRoutes<T extends string> = string;',
	`type DynamicRoutes<T extends string> = ${setToUnionType(dynamicRoutes)};`
	)
	.replace(
	'type DynamicRouteTemplate = string;',
	`type DynamicRouteTemplate = ${setToUnionType(dynamicRouteTemplates)};`
	);
	await fs.writeFile(path.resolve(typesDir, './router.d.ts'), types);
	} catch {}
	},

Pros

• Types are kept in sync
• Types are versioned by expo-router and no longer rely on your @expo/cli version
• expo-router uses the more complex typed-routes declarations, making dog fooding easier

Cons:

• Slightly more verbose syntax
• Types are declared separately from the functions
• expo-router uses the more complex typed-routes declarations, making development slightly harder
• ambient types can be finicky

Feedback wanted

• How do we maintain current versions?
  • Should this be v3 only and we simply manual fix the types for v2?
  • The ClI could check if its expo-router v2 (use old logic) or v3 (use new logic)

We just check of expo-router/types/expo-router.d.ts. If its present we use it

[linear]

ENG-10759 Ensure generated type exports match expo-router standard exports

These should never be out of sync, currently there are a number of types that appear when typed routes is enabled.

[marklawlor]

Example of where types are slightly more complex

[kitten]

Note: These are non-blocking notes, code LGTM 👍
Just leaving this here in case we come back to this

I chatted with @marklawlor about this in regards to:

• this being a d.ts (which we currently need in our approach)
• the potential of isolating this namespace to a module explicitly
• applying interface declaration merging to the routes here and separating this from the generated declaration file.

To keep it short, I believe we've got some wiggle room here in how this could be tweaked and implemented differently.
This should give us some options if we run into any situation where we don't like TypeScript errors or have some bad errors when module/declaration issues are introduced in user code.

All of the mentioned changes have some drawbacks and declaration merging would also imply we'd split this declaration here from a declaration that contains the generated routes. So, they're not trivial changes in how this is approached.
But, if users ever see any overly complex TypeScript errors that aren't clear enough, we can try some of the changes above (or others) to tweak it.

[marklawlor]

@EvanBacon I'm getting this error when I'm trying to use withWatchPlugins and the tsd test runner

 FAIL  src/__typetests__/typed-routes.test.ts
  ● Test suite failed to run

    prompt() {
              return `select which PLATFORMS to run ${chalk.italic(this._getActiveProjectsText())}`;
            } could not be cloned.

      at ChildProcessWorker.send (../../node_modules/jest-worker/build/workers/ChildProcessWorker.js:402:17)

Tests pass when I run as a single project. Just fail when I run all projects. Is there another config option I need on the jest project?

[EvanBacon]

I think watch plugins need to be applied to the individual projects or the entire project, but not both.

[expo-bot]

Hi there! 👋 I'm a bot whose goal is to ensure your contributions meet our guidelines.

I've found some issues in your pull request that should be addressed (click on them for more details) 👇

⚠️ Suggestion: Missing changelog entries

Your changes should be noted in the changelog. Read Updating Changelogs guide and consider adding an appropriate entry to the following changelogs:

• packages/@expo/cli/CHANGELOG.md
• packages/expo-router/CHANGELOG.md

---

Generated by ExpoBot 🤖 against d3be23e