vite-plugin-cpp-loader 2.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. 

package/README.md

@@ -0,0 +1,106 @@
+# vite-cpp-loader
+
+Import `.cpp` files directly into TypeScript. Functions compile to WebAssembly and are callable with full type safety.
+
+## Prerequisites
+
+Emscripten must be installed and `em++` available in your `PATH`.
+
+**macOS:**
+```bash
+brew install emscripten
+```
+
+**Linux / macOS (via emsdk):**
+```bash
+git clone https://github.com/emscripten-core/emsdk.git
+cd emsdk && ./emsdk install latest && ./emsdk activate latest
+source ./emsdk_env.sh
+```
+
+**Windows:**
+```bash
+git clone https://github.com/emscripten-core/emsdk.git
+cd emsdk && emsdk install latest && emsdk activate latest && emsdk_env.bat
+```
+
+## Installation
+
+```bash
+npm install vite-plugin-cpp-loader --save-dev
+```
+
+## Setup
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import cppLoader from 'vite-plugin-cpp-loader';
+
+export default defineConfig({
+  plugins: [cppLoader()]
+});
+```
+
+## Usage
+
+Write plain C++ — no Emscripten boilerplate required. All top-level non-static functions are automatically exported.
+
+**`math.cpp`**
+```cpp
+int add(int a, int b) {
+    return a + b;
+}
+```
+
+**`main.ts`**
+```typescript
+import { add } from './math.cpp';
+
+add(2, 3); // 5
+```
+
+If you only want to export a subset of functions, mark the ones you want to keep internal as `static` and they will be excluded.
+
+## Type safety
+
+Types are inferred from your C++ signatures:
+
+```typescript
+import { add } from './math.cpp';
+
+add(2, 3);     // ✅
+add("2", 3);   // ❌ Argument of type 'string' is not assignable to parameter of type 'number'
+```
+
+Supported C++ → TypeScript mappings:
+
+| C++ | TypeScript |
+|-----|------------|
+| `int`, `float`, `double`, `long`, `short`, `unsigned` | `number` |
+| `int32_t`, `uint32_t`, `int64_t`, `uint64_t`, `size_t` | `number` |
+| `bool` | `boolean` |
+| `std::string`, `const char*` | `string` |
+| `void` | `void` |
+| `emscripten::val` | `any` |
+
+Complex types (STL containers, custom classes) are not supported as parameters or return types.
+
+## Options
+
+```typescript
+cppLoader({
+  emccArgs: ['-sASSERTIONS=1'],   // extra flags passed to em++
+  optimizationLevel: 'O3',         // default: 'O2'
+  cacheDir: '.my-wasm-cache',      // default: 'node_modules/.cpp-wasm'
+  setupVSCode: false,              // disable auto-generation of .vscode/c_cpp_properties.json
+})
+```
+
+## Troubleshooting
+
+**`em++` not found** — make sure Emscripten is installed and in your `PATH`. If you installed via emsdk, run `source ./emsdk_env.sh` before starting the dev server.
+
+## License
+
+MIT

package/dist/compiler.d.ts

@@ -0,0 +1,26 @@
+import { type SpawnOptions } from 'node:child_process';
+import type { CompileResult, CppLoaderOptions } from './types';
+export interface ResolvedOptions extends Required<CppLoaderOptions> {
+    cacheDir: string;
+}
+export interface SpawnResult {
+    code: number;
+    stderr: string;
+}
+type SpawnFn = (cmd: string, args: string[], opts?: SpawnOptions) => Promise<SpawnResult>;
+type FsReadFile = (p: string) => Promise<Buffer | string>;
+type FsWriteFile = (p: string, data: string) => Promise<void>;
+type FsMkdir = (p: string, opts?: {
+    recursive?: boolean;
+}) => Promise<unknown>;
+type FsStat = (p: string) => Promise<unknown>;
+export interface CompilerDeps {
+    spawnFn?: SpawnFn;
+    readFile?: FsReadFile;
+    writeFile?: FsWriteFile;
+    mkdir?: FsMkdir;
+    stat?: FsStat;
+}
+export declare function defaultSpawn(cmd: string, args: string[], opts?: SpawnOptions): Promise<SpawnResult>;
+export declare function compile(id: string, options: ResolvedOptions, isServe: boolean, overrides?: CompilerDeps): Promise<CompileResult>;
+export {};

package/dist/compiler.js

@@ -0,0 +1,92 @@
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { readManifest, scheduleManifestWrite, isCacheValid } from './manifest';
+import { extractTopLevelFunctionNames, buildAutoBindings } from './parser';
+const inFlight = new Map();
+export function defaultSpawn(cmd, args, opts) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(cmd, args, { stdio: ['ignore', 'inherit', 'pipe'], ...opts });
+        const stderrChunks = [];
+        child.stderr?.on('data', (chunk) => {
+            stderrChunks.push(chunk);
+            process.stderr.write(chunk);
+        });
+        child.on('error', (err) => {
+            if (err.code === 'ENOENT') {
+                reject(new Error('em++ not found. Ensure Emscripten is installed and in your PATH.'));
+            }
+            else {
+                reject(err);
+            }
+        });
+        child.on('close', code => {
+            resolve({ code: code ?? 1, stderr: Buffer.concat(stderrChunks).toString() });
+        });
+    });
+}
+function hashContent(content) {
+    return createHash('sha256').update(content, 'utf8').digest('hex').slice(0, 16);
+}
+async function prepareTempFile(id, content, options, deps) {
+    if (content.includes('EMSCRIPTEN_BINDINGS')) {
+        return { compileId: id, cleanup: async () => { } };
+    }
+    const names = extractTopLevelFunctionNames(content);
+    const tmpPath = path.join(options.cacheDir, path.basename(id, '.cpp') + '__tmp.cpp');
+    await deps.writeFile(tmpPath, content + buildAutoBindings(names));
+    return { compileId: tmpPath, cleanup: () => fs.unlink(tmpPath).catch(() => { }) };
+}
+async function doCompile(id, options, isServe, deps) {
+    const content = (await deps.readFile(id)).toString();
+    const hash = hashContent(content);
+    await deps.mkdir(options.cacheDir, { recursive: true });
+    const manifest = await readManifest(options.cacheDir, deps.readFile);
+    const cached = manifest[id];
+    if (await isCacheValid(cached, hash, deps.stat)) {
+        return { jsPath: cached.jsPath, tsdPath: cached.tsdPath };
+    }
+    const baseName = path.basename(id, '.cpp');
+    const jsPath = path.join(options.cacheDir, baseName + '.js');
+    const tsdPath = path.join(options.cacheDir, baseName + '.tsd.d.ts');
+    const { compileId, cleanup } = await prepareTempFile(id, content, options, deps);
+    const args = [
+        compileId,
+        '-o', jsPath,
+        `-${options.optimizationLevel}`,
+        '-sEXPORT_ES6',
+        '-sMODULARIZE',
+        '-sENVIRONMENT=web',
+        '-sALLOW_MEMORY_GROWTH',
+        '-lembind',
+        '--emit-tsd', tsdPath,
+        ...(isServe ? [] : ['-sSINGLE_FILE']),
+        ...options.emccArgs,
+    ];
+    const result = await deps.spawnFn('em++', args);
+    await cleanup();
+    if (result.code !== 0) {
+        throw new Error(`em++ failed to compile ${path.basename(id)}:\n${result.stderr}`);
+    }
+    manifest[id] = { hash, jsPath, tsdPath };
+    scheduleManifestWrite(options.cacheDir, manifest, deps.writeFile);
+    return { jsPath, tsdPath };
+}
+export function compile(id, options, isServe, overrides = {}) {
+    const existing = inFlight.get(id);
+    if (existing)
+        return existing;
+    const deps = {
+        spawnFn: overrides.spawnFn ?? defaultSpawn,
+        readFile: overrides.readFile ?? ((p) => fs.readFile(p)),
+        writeFile: overrides.writeFile ?? ((p, d) => fs.writeFile(p, d)),
+        mkdir: overrides.mkdir ?? ((p, o) => fs.mkdir(p, o)),
+        stat: overrides.stat ?? ((p) => fs.stat(p)),
+    };
+    const promise = doCompile(id, options, isServe, deps).finally(() => {
+        inFlight.delete(id);
+    });
+    inFlight.set(id, promise);
+    return promise;
+}

package/dist/declarations.d.ts

@@ -0,0 +1,2 @@
+import type { CppFunction } from './types';
+export declare function generateDeclarations(functions: CppFunction[]): string;

package/dist/declarations.js

@@ -0,0 +1,7 @@
+export function generateDeclarations(functions) {
+    const lines = functions.map(func => {
+        const params = func.parameters.map(p => `${p.name}: ${p.type}`).join(', ');
+        return `export declare function ${func.name}(${params}): ${func.returnType};`;
+    });
+    return lines.join('\n') + '\n';
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import type { Plugin } from 'vite';
+import type { CppLoaderOptions } from './types';
+export default function cppLoader(options?: CppLoaderOptions): Plugin;

package/dist/index.js

@@ -0,0 +1,55 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { compile } from './compiler';
+import { extractFunctions } from './parser';
+import { generateDeclarations } from './declarations';
+import { generateModule } from './moduleTemplate';
+import { generateCppProperties } from './vscode';
+const DEFAULT_CACHE_DIR = 'node_modules/.cpp-wasm';
+const DEFAULT_OPT_LEVEL = 'O2';
+export default function cppLoader(options = {}) {
+    let isServe = false;
+    let projectRoot = process.cwd();
+    const setupVSCode = options.setupVSCode !== false;
+    const resolvedOptions = {
+        emccArgs: options.emccArgs ?? [],
+        cacheDir: path.resolve(options.cacheDir ?? DEFAULT_CACHE_DIR),
+        optimizationLevel: options.optimizationLevel ?? DEFAULT_OPT_LEVEL,
+        setupVSCode,
+    };
+    return {
+        name: 'vite-cpp-loader',
+        configResolved(config) {
+            isServe = config.command === 'serve';
+            projectRoot = config.root;
+        },
+        buildStart() {
+            if (setupVSCode)
+                generateCppProperties(projectRoot).catch(() => { });
+        },
+        configureServer(server) {
+            server.middlewares.use((req, res, next) => {
+                if (req.url?.endsWith('.wasm')) {
+                    const wasmPath = path.join(resolvedOptions.cacheDir, path.basename(req.url));
+                    res.setHeader('Content-Type', 'application/wasm');
+                    fs.readFile(wasmPath)
+                        .then(content => res.end(content))
+                        .catch(() => next());
+                }
+                else {
+                    next();
+                }
+            });
+        },
+        async load(id) {
+            if (!id.endsWith('.cpp'))
+                return;
+            const result = await compile(id, resolvedOptions, isServe);
+            const functions = await extractFunctions(id, result.tsdPath);
+            const dtsPath = path.join(path.dirname(id), path.basename(id) + '.d.ts');
+            await fs.writeFile(dtsPath, generateDeclarations(functions));
+            this.addWatchFile(result.jsPath);
+            return generateModule(result.jsPath, functions);
+        },
+    };
+}

package/dist/manifest.d.ts

@@ -0,0 +1,4 @@
+import type { CacheManifest } from './types';
+export declare function readManifest(cacheDir: string, readFile: (p: string) => Promise<Buffer | string>): Promise<CacheManifest>;
+export declare function scheduleManifestWrite(cacheDir: string, manifest: CacheManifest, writeFile: (p: string, data: string) => Promise<void>): void;
+export declare function isCacheValid(entry: CacheManifest[string] | undefined, hash: string, stat: (p: string) => Promise<unknown>): Promise<boolean>;

package/dist/manifest.js

@@ -0,0 +1,25 @@
+import path from 'node:path';
+let manifestWriteChain = Promise.resolve();
+export async function readManifest(cacheDir, readFile) {
+    try {
+        const raw = await readFile(path.join(cacheDir, 'manifest.json'));
+        return JSON.parse(raw.toString());
+    }
+    catch {
+        return {};
+    }
+}
+export function scheduleManifestWrite(cacheDir, manifest, writeFile) {
+    manifestWriteChain = manifestWriteChain.then(() => writeFile(path.join(cacheDir, 'manifest.json'), JSON.stringify(manifest, null, 2)));
+}
+export async function isCacheValid(entry, hash, stat) {
+    if (!entry || entry.hash !== hash)
+        return false;
+    try {
+        await stat(entry.jsPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/moduleTemplate.d.ts

@@ -0,0 +1,2 @@
+import type { CppFunction } from './types';
+export declare function generateModule(jsPath: string, functions: CppFunction[]): string;

package/dist/moduleTemplate.js

@@ -0,0 +1,13 @@
+export function generateModule(jsPath, functions) {
+    const moduleUrl = jsPath.replace(/\\/g, '/');
+    const exports = functions.map(func => {
+        const paramNames = func.parameters.map(p => p.name).join(', ');
+        return `export function ${func.name}(${paramNames}) { return _mod.${func.name}(${paramNames}); }`;
+    }).join('\n');
+    return `import createModule from '${moduleUrl}';
+
+const _mod = await createModule();
+
+${exports}
+`;
+}

package/dist/parser.d.ts

@@ -0,0 +1,7 @@
+import type { CppFunction } from './types';
+export declare const CPP_TO_TS: Record<string, string>;
+export declare function parseTsd(tsdContent: string): CppFunction[];
+export declare function parseRegexFallback(cppSource: string): CppFunction[];
+export declare function extractTopLevelFunctionNames(cppSource: string): string[];
+export declare function buildAutoBindings(names: string[]): string;
+export declare function extractFunctions(id: string, tsdPath: string | null): Promise<CppFunction[]>;

package/dist/parser.js

@@ -0,0 +1,122 @@
+import { promises as fs } from 'node:fs';
+export const CPP_TO_TS = {
+    'int': 'number',
+    'float': 'number',
+    'double': 'number',
+    'bool': 'boolean',
+    'void': 'void',
+    'char': 'string',
+    'unsigned': 'number',
+    'long': 'number',
+    'short': 'number',
+    'string': 'string',
+    'std::string': 'string',
+    'const string': 'string',
+    'const std::string': 'string',
+    'int32_t': 'number',
+    'int64_t': 'number',
+    'uint32_t': 'number',
+    'uint64_t': 'number',
+    'size_t': 'number',
+    'const char *': 'string',
+    'char *': 'string',
+    'emscripten::val': 'any',
+};
+function mapType(cppType) {
+    const normalized = cppType.replace(/\s*[&*]\s*$/, '').trim();
+    return CPP_TO_TS[normalized] ?? 'any';
+}
+export function parseTsd(tsdContent) {
+    const functions = [];
+    const methodRegex = /^\s{2}(\w+)\(([^)]*)\):\s*(\S+);/;
+    for (const line of tsdContent.split('\n')) {
+        const match = line.match(methodRegex);
+        if (!match)
+            continue;
+        const [, name, rawParams, returnType] = match;
+        const parameters = rawParams.trim() === ''
+            ? []
+            : rawParams.split(',').map(p => {
+                const paramMatch = p.trim().match(/^(\w+)\s*:\s*(.+)$/);
+                if (!paramMatch)
+                    return { name: 'p', type: 'any' };
+                return { name: paramMatch[1], type: paramMatch[2].trim() };
+            });
+        functions.push({ name, returnType: returnType.replace(';', ''), parameters });
+    }
+    return functions;
+}
+export function parseRegexFallback(cppSource) {
+    // Strip comments then normalize whitespace for multiline signatures
+    const stripped = cppSource
+        .replace(/\/\/[^\n]*/g, '')
+        .replace(/\/\*[\s\S]*?\*\//g, '')
+        .replace(/\n/g, ' ');
+    const functionMap = new Map();
+    const functionRegex = /(\w[\w\s:]*?)\s+(\w+)\s*\(([^)]*)\)\s*\{/g;
+    const bindRegex = /emscripten::function\s*\(\s*"(.*?)"\s*,\s*&(\w+)\s*\)/g;
+    let match;
+    while ((match = functionRegex.exec(stripped)) !== null) {
+        const [, rawReturn, name, rawParams] = match;
+        const returnType = mapType(rawReturn.trim());
+        const parameters = rawParams.trim() === ''
+            ? []
+            : rawParams.split(',').map(param => {
+                const parts = param.trim().split(/\s+/);
+                let type = '';
+                let paramName = '';
+                if (parts[0] === 'const' && parts.length >= 3) {
+                    type = mapType(parts.slice(0, 2).join(' '));
+                    paramName = parts[2]?.replace(/[&*]/g, '') ?? '';
+                }
+                else {
+                    type = mapType(parts[0] ?? '');
+                    paramName = parts[1]?.replace(/[&*]/g, '') ?? '';
+                }
+                return { type, name: paramName };
+            });
+        functionMap.set(name, { name, returnType, parameters });
+    }
+    const functions = [];
+    while ((match = bindRegex.exec(stripped)) !== null) {
+        const [, exposedName, cppName] = match;
+        const func = functionMap.get(cppName);
+        if (func)
+            functions.push({ ...func, name: exposedName });
+    }
+    return functions;
+}
+export function extractTopLevelFunctionNames(cppSource) {
+    const stripped = cppSource
+        .replace(/\/\/[^\n]*/g, '')
+        .replace(/\/\*[\s\S]*?\*\//g, '')
+        .replace(/\n/g, ' ');
+    const names = [];
+    const functionRegex = /(\w[\w\s:]*?)\s+(\w+)\s*\(([^)]*)\)\s*\{/g;
+    let match;
+    while ((match = functionRegex.exec(stripped)) !== null) {
+        const [, rawReturn, name] = match;
+        if (rawReturn.trim().startsWith('static'))
+            continue;
+        names.push(name);
+    }
+    return names;
+}
+export function buildAutoBindings(names) {
+    const lines = names.map(n => `    emscripten::function("${n}", &${n});`).join('\n');
+    return `\n#include <emscripten/bind.h>\n\nEMSCRIPTEN_BINDINGS(module) {\n${lines}\n}\n`;
+}
+export async function extractFunctions(id, tsdPath) {
+    if (tsdPath) {
+        try {
+            const content = await fs.readFile(tsdPath, 'utf-8');
+            if (content.trim().length > 0)
+                return parseTsd(content);
+        }
+        catch {
+            // fall through to regex
+        }
+    }
+    const cppSource = await fs.readFile(id, 'utf-8');
+    return parseRegexFallback(cppSource);
+}

package/dist/types.d.ts

@@ -0,0 +1,24 @@
+export interface CppFunction {
+    name: string;
+    returnType: string;
+    parameters: Array<{
+        type: string;
+        name: string;
+    }>;
+}
+export interface CppLoaderOptions {
+    emccArgs?: string[];
+    cacheDir?: string;
+    optimizationLevel?: 'O0' | 'O1' | 'O2' | 'O3' | 'Os' | 'Oz';
+    /** Auto-generate .vscode/c_cpp_properties.json with Emscripten include paths. Default: true */
+    setupVSCode?: boolean;
+}
+export interface CompileResult {
+    jsPath: string;
+    tsdPath: string;
+}
+export type CacheManifest = Record<string, {
+    hash: string;
+    jsPath: string;
+    tsdPath: string;
+}>;

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/vscode.d.ts

@@ -0,0 +1 @@
+export declare function generateCppProperties(projectRoot: string): Promise<void>;

package/dist/vscode.js

@@ -0,0 +1,44 @@
+import { spawn } from 'node:child_process';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+function getEmscriptenRoot() {
+    return new Promise(resolve => {
+        const child = spawn('em-config', ['EMSCRIPTEN_ROOT'], {
+            stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        const chunks = [];
+        child.stdout?.on('data', (chunk) => chunks.push(chunk));
+        child.on('error', () => resolve(null));
+        child.on('close', code => {
+            resolve(code === 0 ? Buffer.concat(chunks).toString().trim() : null);
+        });
+    });
+}
+export async function generateCppProperties(projectRoot) {
+    const vscodeDir = path.join(projectRoot, '.vscode');
+    const outPath = path.join(vscodeDir, 'c_cpp_properties.json');
+    try {
+        await fs.stat(outPath);
+        return;
+    }
+    catch {
+        // file doesn't exist, generate it
+    }
+    const emRoot = await getEmscriptenRoot();
+    if (!emRoot)
+        return;
+    const includePath = path.join(emRoot, 'system', 'include').replace(/\\/g, '/');
+    const config = {
+        configurations: [
+            {
+                name: 'Emscripten',
+                includePath: ['${workspaceFolder}/**', `${includePath}/**`],
+                cppStandard: 'c++17',
+                intelliSenseMode: 'clang-x64',
+            },
+        ],
+        version: 4,
+    };
+    await fs.mkdir(vscodeDir, { recursive: true });
+    await fs.writeFile(outPath, JSON.stringify(config, null, 2) + '\n');
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "vite-plugin-cpp-loader",
+  "version": "2.0.1",
+  "description": "Vite plugin — import .cpp files as typed ES modules compiled to WebAssembly via Emscripten",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc -p tsconfig.test.json",
+    "prepublishOnly": "npm run typecheck && npm run build"
+  },
+  "keywords": [
+    "vite",
+    "vite-plugin",
+    "cpp",
+    "c++",
+    "webassembly",
+    "wasm",
+    "emscripten",
+    "embind",
+    "native",
+    "loader",
+    "plugin",
+    "typescript",
+    "wasm-bindgen",
+    "cpp-to-wasm"
+  ],
+  "author": "Franco May",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/francomay3/vite-cpp-loader.git"
+  },
+  "homepage": "https://github.com/francomay3/vite-cpp-loader#readme",
+  "bugs": {
+    "url": "https://github.com/francomay3/vite-cpp-loader/issues"
+  },
+  "peerDependencies": {
+    "vite": "^2.0.0 || ^3.0.0 || ^4.0.0 || ^5.0.0 || ^6.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0",
+    "vite": "^5.0.0",
+    "vitest": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}