Template files: expose template API types via a real import (drop tsconfig types requirement)

[guillaumewuip]

Related: #261 — that issue asks for the Template API types to be published via npm (which figma-types now does); this one asks to make them resolvable without tsconfig configuration.

Problem

Template files use a virtual module:

import figma from 'figma'

There is no figma package on npm — the module is injected by the CLI sandbox at execution time (raw_templates.ts rewrites the import to require('figma') before transpiling). TypeScript can therefore only resolve it through the ambient declaration shipped as @figma/code-connect/figma-types, which requires every consuming project to edit its tsconfig.json:

{ "compilerOptions": { "types": ["@figma/code-connect/figma-types"] } }

Pain points:

• Monorepos: one edit per package that owns Code Connect files (dozens for us).
• Packages that already set compilerOptions.types (e.g. for @testing-library/jest-dom) must merge entries manually; @types/* auto-inclusion stops applying, so this is easy to get wrong.
• The ambient figma-types entry also declares a global require, which conflicts with @types/node — hence the need for the separate figma-types-no-require variant.

Proposal

Let template files import the template API from a real module specifier, e.g.:

import figma from '@figma/code-connect/template'

Implementation sketch (sandbox semantics unchanged):

1. New subpath export in package.json:

   "./template": {
     "types": "./template.d.ts",
     "default": "./template.js"
   }

   • template.d.ts: the current figma-types content expressed as a real module (export the API type / a typed default) instead of declare module 'figma'.
   • template.js: a stub that throws at runtime (e.g. "template files are executed by the Code Connect CLI") — it is never loaded in practice since the CLI rewrites the import.
2. CLI: extend figmaImportRegex / import validation in raw_templates.ts to accept the new specifier alongside 'figma', rewriting both to require('figma') before transpilation.
3. Keep the existing 'figma' specifier + figma-types for backward compatibility.

Why a subpath and not the root entry: the root already exports a different figma (the React/HTML parser API — figma.connect, figma.boolean, …). The template API (selectedInstance, figma.code, figma.batch, figma.helpers) is a distinct surface.

Because the specifier becomes a real module, tsc/tsserver resolve its types through normal module resolution — no tsconfig changes needed in consuming projects.

Alternatives considered

• @types/figma on DefinitelyTyped: decouples the types from CLI releases (they must version in lockstep since they describe the template runtime API) and @types auto-inclusion is disabled as soon as a project sets compilerOptions.types, which is common — so it wouldn't fix the main pain point.