GoScript

0.0.84 verified Fri May 01 auth: no javascript

GoScript is an experimental Go-to-TypeScript transpiler that converts Go source code at the AST level into TypeScript, enabling sharing algorithms and business logic between Go backends and TypeScript frontends. Current stable version is 0.0.84 with frequent releases (weekly). Unlike GopherJS (full Go runtime in browser), GoScript aims for readable TypeScript output focused on self-contained algorithms. It supports structs, interfaces, generics, goroutines (mapped to async/await), channels, and limited stdlib. Uses JavaScript number type (64-bit float), no unsafe or complex numbers. Mature enough for sharing logic but not full Go apps.

Common errors

error Error: Cannot find module 'goscript' ↓

cause The 'goscript' package is not installed or not added to dependencies.

fix

npm install goscript@latest

error TypeError: compile is not a function ↓

cause Importing the module incorrectly (e.g., default import instead of named import).

fix

Use named import: import { compile } from 'goscript';

error SyntaxError: Unexpected token 'export' ↓

cause Using CommonJS require() with an ES module.

fix

Change to ES module import or use dynamic import: import('goscript')

error Error: Package 'fs' is not supported yet ↓

cause Attempting to compile a Go package that uses an unsupported standard library package.

fix

Remove or replace the unsupported package with a compatible alternative.

Warnings

gotcha Go's int types (int, int64, uint32, etc.) are all translated to JavaScript's number type (64-bit float). Bitwise operations are truncated to 32 bits. Use BigInt if you need 64-bit integer precision. ↓

fix Manually cast to BigInt in generated TypeScript if exact integer math is required.

breaking Since v0.0.81, generated imports use .ts extension (e.g., import './foo.ts' instead of './foo'). This may break projects that rely on module resolution without extension. ↓

fix Ensure your bundler or tsconfig resolves .ts imports correctly (e.g., moduleResolution: 'bundler').

breaking Pointer types are compiled to VarRef system; direct pointer arithmetic is not supported and will cause compilation errors. ↓

fix Avoid using uintptr or unsafe.Pointer; refactor code to use slices or references instead.

gotcha Goroutines and channels are translated to async/await. All functions that use channels become async, potentially requiring callers to await them. This can cause 'Top-level await' errors if not handled. ↓

fix Wrap async calls in an async IIFE or use top-level await if your target supports it.

deprecated The 'goscript' package is pre-v1.0 (v0.0.84). APIs may change without major version bump. There is no stable public API yet. ↓

fix Pin to a specific version and expect to update imports when upgrading.

gotcha Standard library support is incomplete. Many packages (e.g., net/http, os) are not fully implemented. Attempting to compile code using unsupported packages will fail. ↓

fix Check the list of supported packages in the documentation before compiling.

gotcha Reflection is partially implemented. Some reflection features (like accessing unexported fields) may not work correctly. ↓

fix Avoid relying on advanced reflection in code meant for compilation.

Install

npm install goscript

yarn add goscript

pnpm add goscript

Imports

goscript (CLI)
wrong
```
const goscript = require('goscript')
```
correct
```
import { goscript } from 'goscript'
```
Package provides the compiler as a library; use the binary for CLI usage.

compile

wrong

import * as goscript from 'goscript'; goscript.compile(...)

correct

import { compile } from 'goscript'

Named export 'compile' is available for programmatic compilation.

GoscriptOptions
```
import { GoscriptOptions } from 'goscript'
```
TypeScript type for compile options, available since v0.0.80.

Quickstart

Shows how to use the compile function to transpile a simple Go program to TypeScript programmatically.

import { compile } from 'goscript';
import { writeFileSync, mkdirSync } from 'fs';
import { join } from 'path';

const goCode = `
package main

import "fmt"

func main() {
    fmt.Println("Hello from GoScript!")
}
`;

const result = compile({
  files: { 'main.go': goCode },
  packagePath: 'main',
  outdir: './dist',
});

mkdirSync('./dist', { recursive: true });
writeFileSync(join('./dist', 'main.ts'), result.code, 'utf8');
console.log('Compiled successfully!');