solc-rts — pragma-aware Solidity compiler (programmatic)

Compile any Solidity file with the exact solc version detected from its pragma solidity.

• Strict by default (uses only locally available compilers)
• Auto mode (auto: true) will:
  1. try a remote solc snapshot, and
  2. if blocked, generate & run a temporary .bat/.sh to install the exact [email protected] alias (e.g., solc-0516), then compile.

1) Installation

npm install solc-rts

Optional (slow/blocked networks):

npm config set registry https://registry.npmmirror.com

2) Quick start (server.js)

Create server.js:

// server.js
const { compileFile } = require('solc-rts');

(async () => {
  try {
    await compileFile('./contracts/MyContract.sol', {
      outDir: './artifacts',
      auto: true,      // enable remote & installer fallback
      optimize: true,  // solc optimizer ON
      runs: 200,       // optimizer runs
      // registry: 'https://registry.npmmirror.com', // optional registry for auto-install
    });
    process.exitCode = 0;
  } catch (err) {
    console.error(err);
    process.exitCode = 1;
  }
})();

Project layout example:

your-project/
├─ contracts/
│  └─ MyContract.sol
├─ artifacts/          # will be created with compiled artifacts
├─ server.js
└─ package.json

Run it:

node ./server.js

Artifacts (ABI + bytecode) will be written to ./artifacts/<Contract>.json.

3) API — compileFile(entryPath, options)

async function compileFile(
  entryPath: string,
  options?: {
    outDir?: string;     // default: "build"
    optimize?: boolean;  // default: false
    runs?: number;       // default: optimize ? 200 : 0
    auto?: boolean;      // default: false (strict mode)
    registry?: string;   // optional npm registry for auto-install
    log?: (...args:any[]) => void; // optional logger (defaults to console.log)
  }
): Promise<{ count: number; outDir: string; artifacts: Map<string, any>; }>;

Behavior summary

• Reads the contract, parses pragma solidity ..., extracts exact x.y.z (first x.y.z in the pragma).
• Strict mode (auto: false):
  • Uses matching local alias (solc-<xyz>) if present, else uses your project’s default solc only if it matches exactly.
  • If no match, throws with an install hint:

    npm i -D solc-0516@npm:[email protected]

• Auto mode (auto: true):
  • Try remote solc snapshot → if that fails, run a .bat/.sh to install solc-<xyz>@npm:solc@<x.y.z> (honors registry if provided) → compile.

Options reference

| Option | Type | Default | Description | |-------------|-----------|----------------------|-------------| | outDir | string | "build" | Output folder for artifacts (<Contract>.json with abi, evm.bytecode, etc.). | | optimize | boolean | false | Enable solc optimizer. | | runs | number | optimize ? 200 : 0 | Optimizer runs; used only when optimize is true. | | auto | boolean | false | Allow remote & installer fallback when exact solc isn’t local. | | registry | string | (none) | NPM registry used in auto-install scripts (useful behind corporate proxies). | | log | function| console.log | Custom logger for progress output. |

Return

• count: number of artifacts written
• outDir: resolved output directory
• artifacts: Map<"FilePath:ContractName", ArtifactJson>

4) Examples

A) Strict mode (no auto-install):

await compileFile('./contracts/Legacy.sol', {
  outDir: './build',
  auto: false,        // strict
  optimize: false,
});

If no exact compiler is found, you’ll see an actionable hint.

B) Auto mode with mirror registry:

await compileFile('./contracts/Legacy.sol', {
  outDir: './artifacts',
  auto: true,
  registry: 'https://registry.npmmirror.com',
});

5) Troubleshooting

• Behind a corporate proxy / blocked network

  npm config set registry https://registry.npmmirror.com
  npm config set proxy http://USER:PASSWORD@HOST:PORT
  npm config set https-proxy http://USER:PASSWORD@HOST:PORT

• “Installed but cannot require alias”
  Make sure you run from the project root where node_modules is located.
• Version mismatch
  Ensure the pragma includes a concrete x.y.z. This tool targets the first explicit x.y.z it finds.

6) License

MIT