goscript

library0.0.84jsnpmunverified

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.

serialization

npm install goscript

github ↗package ↗

INSTALL

IMPORT

SIG · GOSCRIPT

goscript

serializationjavascriptv0.0.84

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

goscript (CLI)

✓ import { goscript } from 'goscript'

✗ const goscript = require('goscript')

Package provides the compiler as a library; use the binary for CLI usage.

compile

✓ import { compile } from 'goscript'

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

Named export 'compile' is available for programmatic compilation.

GoscriptOptions

✓ import { GoscriptOptions } from 'goscript'

TypeScript type for compile options, available since v0.0.80.

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!');

goscript --version

Debug

Known issues

gotchaGo'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.

affects: >=0.0.1

breakingSince 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').

affects: >=0.0.81

breakingPointer 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.

affects: >=0.0.1

gotchaGoroutines 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.

affects: >=0.0.1

deprecatedThe '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.

affects: <1.0.0

gotchaStandard 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.

affects: >=0.0.1

gotchaReflection 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.

affects: >=0.0.1

Errors

Common errors & fixes

Error: Cannot find module 'goscript'

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

fix

npm install goscript@latest

TypeError: compile is not a function

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

fix

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

SyntaxError: Unexpected token 'export'

Using CommonJS require() with an ES module.

fix

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

Error: Package 'fs' is not supported yet

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

fix

Remove or replace the unsupported package with a compatible alternative.

Upgrade

Version history

0.0.84latest on npm

Audit

Dependencies

typescriptoptionalGenerated code uses TypeScript features, requires TypeScript compiler for checking

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/aperturerobotics/goscript ↗

packagehttps://www.npmjs.com/package/goscript ↗