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

Abierto
  • ¿Algo no está bien?
#406 0 comentarios 2 reacciones 0 asignados Ver en GitHub

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
4/5
Tiempo estimado
3-5 días
Aptitud para principiantes
46/100
Tipo de issue
Nueva funcionalidad
Claridad
Bien especificado
Estado de actividad
Activo
Stack tecnológico
node.js, typescript
Área
developer-experience, tooling

Línea de trabajo

Start by reading package.json and raw_templates.ts to understand the existing exports and how template imports are validated and rewritten. Then inspect the current figma-types declaration and its tests, if present, to see how the template API is typed. Done means the new subpath resolves through normal TypeScript module resolution and the CLI still rewrites it to the sandbox import while preserving existing 'figma' support.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.
Lenguaje dominante
TypeScript
Estrellas
1.6k
Forks
126
Sin PR fusionados en 30 d

Preparar el entorno

Este proyecto no incluye contenedor de desarrollo, Dockerfile ni guía de contribución, así que la configuración corre por tu cuenta: empieza por su README y consulta nuestra guía para la primera contribución para los pasos generales.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de figma/code-connect

Todos los issues de figma/code-connect

Issues similares

Más issues de TypeScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.