ton-compiler

2.3.0 verified Fri May 01 auth: no javascript

Provides pre-built binaries for compiling TON FunC and Tact smart contracts to Fift and BOC (Bag of Cells) output. Version 2.3.0 supports FunC 0.4.4+ and Tact 1.3.0. Distributed as a npm package wrapping native binaries for major platforms (Linux, macOS, Windows). Updated quarterly alongside TON compiler releases. Key differentiator: eliminates need to manually download or build TON compilers; integrates seamlessly with JavaScript/TypeScript tooling like Blueprint or Tact boilerplate.

Common errors

error Error: Cannot find module 'ton-compiler' ↓

cause Missing dependency or wrong import path

fix

Install: npm install ton-compiler

error Error: ENOENT: no such file or directory, stat '/path/to/node_modules/ton-compiler/bin/linux-x64/func' ↓

cause Platform binary not downloaded or unsupported platform

fix

Run: npx ton-compiler postinstall. If unsupported, manually add binary or use Docker.

error TypeError: compile is not a function ↓

cause Wrong import (e.g., default import used incorrectly)

fix

Use named import: import { compile } from 'ton-compiler'

Warnings

breaking v2.0.0 renamed compileFunc to compileWithFunc and changed config shape ↓

fix Use compile instead of compileFunc; pass an object with targets and sources.

gotcha Binary download may fail behind a proxy ↓

fix Set HTTP_PROXY/HTTPS_PROXY environment variables, or manually download and place binary in node_modules/ton-compiler/bin/.

gotcha compiler binary not found on install ↓

fix Run npx ton-compiler postinstall or npm rebuild ton-compiler. If still fails, check platform support (linux-x64, darwin-arm64, etc.).

breaking v3.0.0 drops support for Node.js < 18 ↓

fix Upgrade Node.js to version 18 or later.

Install

npm install ton-compiler

yarn add ton-compiler

pnpm add ton-compiler

Imports

compile
wrong
```
const { compile } = require('ton-compiler')
```
correct
```
import { compile } from 'ton-compiler'
```
ESM is the default since v2.0.0; CJS require may work but not recommended for Node >= 16.
CompilerConfig
```
import { CompilerConfig } from 'ton-compiler'
```
Type import for configuring compiler options; optional, can be inferred.
compileWithFunc
wrong
```
import { compileFunc } from 'ton-compiler'
```
correct
```
import { compileWithFunc } from 'ton-compiler'
```
Function renamed in v2.0.0 from compileFunc to compileWithFunc; old import will fail.

Quickstart

Compiles a minimal FunC contract to BOC and prints its hash.

import { compile } from 'ton-compiler';
import { Cell } from '@ton/core';

async function main() {
  const sourceCode = `
#include "imports/stdlib.fc";
() recv_internal(int my_balance, int msg_value, cell in_msg_full, slice in_msg_body) impure {
  ;; do nothing
}
`;
  const result = await compile({
    targets: ['func'],
    sources: { 'main.fc': sourceCode },
    sourcesConfig: { root: 'main.fc' },
  });
  const boc = Cell.fromBoc(result.output)[0];
  console.log('Compiled contract code hash:', boc.hash().toString('hex'));
}
main().catch(console.error);