# TypeScript-Go Output Format: How the tsgo CLI Emits JavaScript and Declaration Files

> Explore TypeScript-Go output formats. Discover how the tsgo CLI emits JavaScript, declaration files, and more, leveraging official TypeScript compiler logic for consistent results.

- Repository: [Microsoft/typescript-go](https://github.com/microsoft/typescript-go)
- Tags: how-to-guide
- Published: 2026-04-25

---

**The TypeScript-Go compiler (tsgo) produces JavaScript files (`.js`, `.mjs`, `.cjs`, or `.jsx`), optional source maps (`.js.map`), TypeScript declaration files ([`.d.ts`](https://github.com/microsoft/typescript-go/blob/main/.d.ts)), declaration maps (`.d.ts.map`), and incremental build info files (`.tsbuildinfo`) using the same emission logic as the official TypeScript compiler.**

The `microsoft/typescript-go` repository implements a native Go port of the TypeScript compiler, exposing the `tsgo` CLI for drop-in compatibility with existing TypeScript workflows. Understanding the typescript-go output format helps developers configure build pipelines, as the tool replicates `tsc` behavior while delivering significantly faster compilation performance.

## JavaScript File Emission and Extension Mapping

The core mechanism for determining output extensions resides in [`internal/outputpaths/outputpaths.go`](https://github.com/microsoft/typescript-go/blob/main/internal/outputpaths/outputpaths.go). The `GetOutputExtension` function examines the source file's extension and the `--jsx` compiler option to decide the resulting JavaScript file type.

```go
func GetOutputExtension(fileName string, jsx core.JsxEmit) string {
    switch {
    case tspath.FileExtensionIs(fileName, tspath.ExtensionJson):
        return tspath.ExtensionJson
    case jsx == core.JsxEmitPreserve && tspath.FileExtensionIsOneOf(fileName, []string{tspath.ExtensionJsx, tspath.ExtensionTsx}):
        return tspath.ExtensionJsx
    case tspath.FileExtensionIsOneOf(fileName, []string{tspath.ExtensionMts, tspath.ExtensionMjs}):
        return tspath.ExtensionMjs
    case tspath.FileExtensionIsOneOf(fileName, []string{tspath.ExtensionCts, tspath.ExtensionCjs}):
        return tspath.ExtensionCjs
    default:
        return tspath.ExtensionJs
    }
}

```

*Reference: [`internal/outputpaths/outputpaths.go#L9-L22`](https://github.com/microsoft/typescript-go/blob/main/internal/outputpaths/outputpaths.go#L9)*

### Extension Resolution Logic

The function applies the following rules when mapping source files to output extensions:

- **`.ts`** or **`.tsx`** (standard): Emits `.js`
- **`.mts`** or **`.mjs`**: Emits `.mjs` (ES modules)
- **`.cts`** or **`.cjs`**: Emits `.cjs` (CommonJS)
- **`.tsx`** or **`.jsx`** with `--jsx preserve`: Emits `.jsx` (JSX preserved)
- **`.json`**: Passes through unchanged as `.json`

The computed extension feeds into `getOwnEmitOutputFilePath`, which prefixes the output directory (if configured) and constructs the final filesystem path.

## Declaration Files and Source Maps

TypeScript-Go generates additional artifacts based on compiler options passed to the CLI.

### Declaration File Emission

When `declaration: true` is set (or `--emitDeclarationOnly` is used), the compiler invokes `GetDeclarationEmitOutputFilePath` in [`internal/outputpaths/outputpaths.go`](https://github.com/microsoft/typescript-go/blob/main/internal/outputpaths/outputpaths.go) to produce [`.d.ts`](https://github.com/microsoft/typescript-go/blob/main/.d.ts) files:

```go
func GetDeclarationEmitOutputFilePath(file string, options *core.CompilerOptions, host OutputPathsHost) string {
    // …determine output directory…
    declarationExtension := tspath.GetDeclarationEmitExtensionForPath(path) // always ".d.ts"
    return tspath.RemoveFileExtension(path) + declarationExtension
}

```

*Reference: [`internal/outputpaths/outputpaths.go#L24-L41`](https://github.com/microsoft/typescript-go/blob/main/internal/outputpaths/outputpaths.go#L24)*

### Source Map Generation

Source maps are emitted when `sourceMap: true` and `inlineSourceMap: false`. The `GetSourceMapFilePath` function appends `.map` to the JavaScript output path:

```go
func GetSourceMapFilePath(jsFilePath string, options *core.CompilerOptions) string {
    if options.SourceMap.IsTrue() && !options.InlineSourceMap.IsTrue() {
        return jsFilePath + ".map"
    }
    return ""
}

```

*Reference: [`internal/outputpaths/outputpaths.go#L93-L99`](https://github.com/microsoft/typescript-go/blob/main/internal/outputpaths/outputpaths.go#L93)*

## Incremental Build Information

For incremental compilation or project-reference builds, TypeScript-Go generates a `.tsbuildinfo` file via `GetBuildInfoFileName`:

```go
func GetBuildInfoFileName(options *core.CompilerOptions, opts tspath.ComparePathsOptions) string {
    // …compute output location…
    return buildInfoExtensionLess + tspath.ExtensionTsBuildInfo // ".tsbuildinfo"
}

```

*Reference: [`internal/outputpaths/outputpaths.go#L200-L222`](https://github.com/microsoft/typescript-go/blob/main/internal/outputpaths/outputpaths.go#L200)*

This file is created when `incremental: true` is enabled or when using `--build` mode, caching program state for faster subsequent compilations.

## Command-Line Examples

### Basic Compilation

Compile a single file to JavaScript without additional artifacts:

```bash
npx tsgo foo.ts

# Output: ./foo.js

```

### Enable Source Maps

Generate separate `.js.map` files for debugging:

```bash
npx tsgo foo.ts --sourceMap

# Outputs: ./foo.js, ./foo.js.map

```

### Emit Type Declarations

Produce [`.d.ts`](https://github.com/microsoft/typescript-go/blob/main/.d.ts) files alongside JavaScript:

```bash
npx tsgo foo.ts --declaration

# Outputs: ./foo.js, ./foo.d.ts

```

### Preserve JSX Syntax

Maintain JSX syntax in the output for transformer processing:

```bash
npx tsgo component.tsx --jsx preserve

# Output: ./component.jsx

```

### Module-Specific Output

Leverage ES module or CommonJS specific extensions:

```bash

# ES modules

npx tsgo lib.mts

# Output: lib.mjs

# CommonJS

npx tsgo lib.cts

# Output: lib.cjs

```

### Incremental Build

Enable build caching for large projects:

```bash
npx tsgo project/tsconfig.json --incremental

# Outputs: compiled JS files, ./tsconfig.tsbuildinfo

```

## Key Source Files

- **CLI Entry Point**: [`cmd/tsgo/main.go`](https://github.com/microsoft/typescript-go/blob/main/cmd/tsgo/main.go) ([link](https://github.com/microsoft/typescript-go/blob/main/cmd/tsgo/main.go))
- **Command Execution**: [`internal/execute/commandline.go`](https://github.com/microsoft/typescript-go/blob/main/internal/execute/commandline.go) ([link](https://github.com/microsoft/typescript-go/blob/main/internal/execute/commandline.go))
- **Output Path Logic**: [`internal/outputpaths/outputpaths.go`](https://github.com/microsoft/typescript-go/blob/main/internal/outputpaths/outputpaths.go) ([link](https://github.com/microsoft/typescript-go/blob/main/internal/outputpaths/outputpaths.go))
- **Path Utilities**: [`internal/tspath/extension.go`](https://github.com/microsoft/typescript-go/blob/main/internal/tspath/extension.go) ([link](https://github.com/microsoft/typescript-go/blob/main/internal/tspath/extension.go))

## Summary

- **TypeScript-Go** mirrors the official TypeScript compiler's output format, ensuring drop-in compatibility with existing toolchains.
- The `GetOutputExtension` function in [`internal/outputpaths/outputpaths.go`](https://github.com/microsoft/typescript-go/blob/main/internal/outputpaths/outputpaths.go) determines whether to emit `.js`, `.mjs`, `.cjs`, or `.jsx` based on source extensions and the `--jsx` flag.
- **Declaration files** ([`.d.ts`](https://github.com/microsoft/typescript-go/blob/main/.d.ts)) generate when `declaration: true`, while **source maps** (`.js.map`) require `sourceMap: true` and `inlineSourceMap: false`.
- **Build info files** (`.tsbuildinfo`) support incremental compilation when enabled via `--incremental` or `--build` flags.
- Entry points [`cmd/tsgo/main.go`](https://github.com/microsoft/typescript-go/blob/main/cmd/tsgo/main.go) and [`internal/execute/commandline.go`](https://github.com/microsoft/typescript-go/blob/main/internal/execute/commandline.go) orchestrate the emission process by invoking path calculation logic before writing files.

## Frequently Asked Questions

### What file extensions does TypeScript-Go generate?

TypeScript-Go emits `.js` for standard TypeScript files, `.mjs` for `.mts` sources, `.cjs` for `.cts` sources, and `.jsx` when compiling `.tsx` files with `--jsx preserve`. It optionally produces [`.d.ts`](https://github.com/microsoft/typescript-go/blob/main/.d.ts) declarations, `.js.map` source maps, and `.tsbuildinfo` incremental build files.

### How do I enable source maps in tsgo?

Pass the `--sourceMap` flag on the command line. TypeScript-Go checks `options.SourceMap.IsTrue()` and ensures `options.InlineSourceMap.IsTrue()` is false to emit separate `.js.map` files alongside your JavaScript output, as implemented in `GetSourceMapFilePath`.

### Does TypeScript-Go support incremental compilation?

Yes. When you specify `--incremental` or use `--build` mode for project references, TypeScript-Go calls `GetBuildInfoFileName` to generate a `.tsbuildinfo` file. This caches the program's state, allowing subsequent compilations to skip unchanged files and significantly improve build times.

### How does tsgo output differ from the standard TypeScript compiler (tsc)?

There is no difference in output format. TypeScript-Go is designed as a native Go port that produces byte-identical JavaScript, declarations, and source maps compared to the official TypeScript compiler. The logic in [`internal/outputpaths/outputpaths.go`](https://github.com/microsoft/typescript-go/blob/main/internal/outputpaths/outputpaths.go) replicates `tsc` behavior exactly, ensuring existing build configurations remain compatible.