# TypeScript y módulos

Elide ejecuta archivos `.ts`, `.mts`, `.cts` y `.tsx` eliminando sus tipos; no comprueba los tipos ni lee
`tsconfig.json`.

## Argumentos del script

Los archivos de entrada de JavaScript y TypeScript reciben la misma disposición de `process.argv`: la ruta del
ejecutable, la ruta absoluta del archivo de entrada y después los argumentos de la aplicación. Por ejemplo:

```bash
elide --timeout=10s run main.ts -- alpha 'two words'
```

Aquí `process.argv.slice(2)` es `["alpha", "two words"]`; ni `--timeout=10s` ni `run` aparecen en el array. La
ejecución directa (`elide main.ts -- alpha 'two words'`) usa la misma disposición, igual que un script con nombre del
manifiesto que invoca el archivo de entrada. `process.execArgv` está vacío; no contiene opciones del lanzador de Elide.
El primer `--` separa los argumentos del lanzador de los de la aplicación; los `--` posteriores se conservan como
argumentos de la aplicación.

## Sintaxis de TypeScript

| Sintaxis | Estado |
| --- | --- |
| Anotaciones de tipo, interfaces, `type`, genéricos, `as`, `satisfies`, `!` | Se eliminan |
| `import type`, `import { type X }` | Se eliminan |
| `enum`, `const enum` | Se compilan a objetos |
| `namespace` | Se compila |
| Propiedades de parámetro del constructor (`constructor(public x: number)`) | Se compilan |
| `abstract`, campos `declare`, `override`, `accessor` | Compatibles |
| `import fs = require("node:fs")` | Compatible |
| Decoradores en clases y métodos | Decoradores estándar: cada uno recibe `(value, context)` |
| Decoradores al estilo de `experimentalDecorators` | No compatibles; reciben los argumentos estándar |
| Decoradores de parámetro (`constructor(@inject x)`) | `SyntaxError: … expected BindingIdentifier or BindingPattern` |
| Aserciones de tipo `<string>value` | `Precompiler failed with 1 diagnostic(s): … [ERROR] Unexpected token`; use `value as string` |
| `export = value` | `SyntaxError: … Expected an operand but found export` |
| `paths` de `tsconfig.json` | Se ignora: `TypeError: Module not found: '@lib/math'` |

Las importaciones pueden nombrar el archivo `.ts`, una extensión `.js` o ninguna extensión; las tres se resuelven a
`math.ts`:

```ts
import { add } from "./src/lib/math.ts";
import { add as add2 } from "./src/lib/math.js";
import { add as add3 } from "./src/lib/math";
console.log(add(1, 2), add2(2, 2), add3(3, 3));
```

```text
3 4 6
```

## JSX

Los archivos `.tsx` usan el runtime automático de JSX e importan `react/jsx-runtime`. Instale React usted mismo:

```tsx
// app.tsx
import { renderToString } from "react-dom/server";

function Hello({ name }: { name: string }) {
  return <p>hello {name}</p>;
}

console.log(renderToString(<Hello name="elide" />));
```

```bash
elide install --ecosystems=npm   # react, react-dom in package.json
elide app.tsx
```

```text
<p>hello <!-- -->elide</p>
```

| Entrada | Resultado |
| --- | --- |
| `/** @jsxImportSource preact */` al principio de un archivo `.tsx` | Importa `preact/jsx-runtime` |
| `jsxImportSource` en `tsconfig.json` | Se ignora; se usa React |
| `/** @jsx h */` | Se ignora; se crean elementos de React |
| JSX en un archivo `.jsx` | `SyntaxError: … Expected an operand but found <`; cambie su extensión a `.tsx` |

## Comprobar los tipos

Instale TypeScript y ejecute su compilador a través de Elide:

```json
{
  "scripts": { "typecheck": "tsc --noEmit" },
  "devDependencies": { "typescript": "^5.9.0", "@types/node": "^24.0.0" }
}
```

```json
{
  "compilerOptions": {
    "module": "nodenext",
    "target": "esnext",
    "strict": true,
    "noEmit": true,
    "allowImportingTsExtensions": true,
    "erasableSyntaxOnly": true,
    "verbatimModuleSyntax": true,
    "types": ["node"]
  }
}
```

```bash
elide install --ecosystems=npm
elide run typecheck              # or: elide run tsc
```

```text
bad-types.ts(1,7): error TS2322: Type 'string' is not assignable to type 'number'.
```

`tsc` termina con `2` cuando hay errores de tipos. Pase las opciones del compilador después de `--`:
`elide run tsc -- --version`. Con `erasableSyntaxOnly`, `tsc` rechaza los enums, los namespaces y las propiedades de
parámetro; quítela si los usa.

## Tipos de Elide

`@elide-dev/types` declara los globales y módulos propios de Elide e incluye `@types/node`. Añádalo como dependencia
de desarrollo y nómbrelo en `types`:

```json
{
  "type": "module",
  "scripts": { "typecheck": "tsc --noEmit" },
  "devDependencies": { "typescript": "^5.9.0", "@elide-dev/types": "nightly" }
}
```

```json
{
  "compilerOptions": {
    "module": "nodenext",
    "target": "esnext",
    "strict": true,
    "noEmit": true,
    "allowImportingTsExtensions": true,
    "types": ["@elide-dev/types"]
  }
}
```

```ts
// main.ts
import { Database } from "elide:postgres";
import { readFileSync } from "node:fs";

const bytes: number = readFileSync("package.json").length;
console.log(`Elide ${Elide.version}: ${bytes} bytes`);
export const open = (url: string) => Database.connect(url);
```

```bash
elide install --ecosystems=npm
elide run typecheck
elide main.ts
```

```text
Elide 1.6.0: 149 bytes
```

| API | Declarada |
| --- | --- |
| `Elide.version`, `debug`, `release`, `buildMode` | Sí |
| `Elide.targetArchitecture` | Tipada como `boolean`; el valor es una cadena |
| `Elide.serve()` | No: `Property 'serve' does not exist` |
| `elide:postgres`, `elide:mysql` | Sí |
| `elide:sqlite`, `elide:cel`, `elide:csv`, `elide:yaml`, `elide:telemetry` | No |
| `import … from "./script.py"` | Sí, como `any` |
| Módulos `node:*` | Sí, a través de `@types/node` |

La etiqueta `nightly` sigue las declaraciones más recientes; `latest` es más antigua.

## Módulos ES y CommonJS

| Archivo | Sistema de módulos |
| --- | --- |
| `.mjs`, `.mts` | Módulo ES |
| `.cjs`, `.cts` | CommonJS |
| `.ts`, `.tsx` | Módulo ES |
| `.js` | Módulo ES cuando el `package.json` más cercano tiene `"type": "module"`; si no, CommonJS |

Un archivo `.js` con sentencias `import` y sin `"type": "module"` falla con
`SyntaxError: … Expected an operand but found import`; añada el campo o cambie la extensión del archivo a `.mjs`.

| Característica | Comportamiento |
| --- | --- |
| `import lib, { a } from "./lib.cjs"` | `module.exports` es la exportación por defecto y sus propiedades son exportaciones con nombre |
| `await import("./lib.cjs")` | Funciona |
| `require("./lib.mjs")` | `Error: require() of ES Module … not supported.` (`ERR_REQUIRE_ESM`); use `await import()` |
| `createRequire(import.meta.url)` | Funciona |
| `import.meta.url`, `.filename`, `.dirname` | Funcionan |
| `import.meta.main`, `import.meta.resolve` | `undefined` |
| `__dirname` en CommonJS | Funciona |
| `__filename` en el archivo CommonJS de entrada | `"unknown"`; use `module.filename`. Los archivos cargados con require obtienen la ruta real. |
| `__dirname`, `require` en módulos ES | Definidos, a diferencia de Node; no dependa de ellos |

## JSON

Todas estas formas cargan `data.json`:

```js
import data from "./data.json" with { type: "json" };
import same from "./data.json";
const viaRequire = require("./data.json"); // CommonJS
```

## `exports` e `imports` del paquete

| Campo de `package.json` | `import` | `require()` |
| --- | --- | --- |
| Subrutas de `exports` (`"./feature": …`) | Funciona | Funciona |
| `exports` para la raíz del paquete, con `main` | Funciona | Usa `main` |
| `exports` para la raíz del paquete, sin `main` | Funciona | `Error: Cannot find module 'pkg'` |
| Condiciones `import` y `default` | Funcionan | — |
| Una condición `require` listada antes de `default` | Se elige en lugar de `default` | — |
| Subruta no exportada | `Package subpath is not defined by "exports" field` (sin `code`) | — |
| `imports` (`"#internal"`) | `TypeError: Packages imports do not define the specifier: '#internal'` | `Error: Cannot find module '#internal'` |

## Ejemplos

- [TypeScript sin compilación](/docs/code-samples#typescript-without-a-build)

## Véase también

- [JavaScript y TypeScript](/docs/web)
- [Usuarios de Node](/docs/elide-for-node)
- [Instalador npm](/docs/toolchain/web/npm)
