Imports & Includes

As your project grows, you will want to split your code into multiple files. BlueScript handles dependencies differently depending on whether you are loading BlueScript Modules or local C / header files.

Importing BlueScript Modules

You can create reusable BlueScript code (.bs files) and import them into other files.

1. Local Modules

To import a module from your own project, use the relative path (starting with ./ or ../).

BlueScript, C (.c), and header (.h) files must be placed under the srcDir directory configured in bsconfig.json. Relative import paths must resolve to files inside srcDir.

src/math-utils.bs (The library)

// Named export
export function add(a: integer, b: integer): integer {
    return a + b;
}

// ❌ Default export is NOT supported
// export default function ...

src/index.bs (The importer)

// Import using relative path
import { add } from "./math-utils";

console.log(add(10, 20));

No Default Exports

BlueScript currently supports only Named Exports. You must use import { name } syntax. import name from ... will not work.

2. Package Modules

When you install an external library (like a driver), you import it by its Package Name, not a file path.

// Import from an installed package
// The compiler resolves "gpio" from your project config
import { GPIO } from "gpio";

Including C and Header Files

You can use local .c and .h files in your project via Inline C #include directives. Place them under srcDir, alongside your .bs files.

Unlike system headers, paths in quotes are resolved relative to the current .bs file (same rule as local BlueScript imports). For details on writing C code inside code blocks, see Inline C.

src/
  index.bs
  driver.h    # C function declarations
  driver.c    # C function implementations

Option 1: Include a .c file directly

Best for small, self-contained helpers.

src/native-lib.c

int native_multiply(int a, int b) {
    return a * b;
}

src/index.bs

code`#include "./native-lib.c"`

export function multiply(a: integer, b: integer): integer {
    let result = 0;
    code`${result} = native_multiply(${a}, ${b});`
    return result;
}

console.log(multiply(3, 4));

Option 2: Use a header and a separate .c file (recommended)

Best when porting existing C code or splitting declarations from implementation. The build system compiles .c files under srcDir automatically; include the .h from BlueScript so the generated C code sees the function declarations.

src/add.h

int add(int a, int b);

src/add.c

#include "add.h"

int add(int a, int b) {
    return a + b;
}

src/index.bs

code`#include "add.h"`

function main(): void {
    let result: integer = 0;
    code`${result} = add(10, 20);`
    console.log(result);
}

main();

Path rules

• "./file.c" or "file.h" — project-local, relative to the current .bs file
• <math.h> — system or ESP-IDF headers (see Inline C)

File naming

Do not use the bs_ prefix for C source file names. That prefix is reserved for files generated by the BlueScript compiler.

Summary table

Source Type	Syntax	Path Style	Example
Local BS Module	import { ... }	Relative to .bs	"./utils"
Package BS Module	import { ... }	Package Name	"gpio"
Local C File	code`#include ...`	Relative to .bs	"./driver.c"
Local Header File	code`#include ...`	Relative to .bs	"driver.h"

When you include a .h file, place the corresponding .c implementation under srcDir. The build system compiles it automatically; BlueScript only needs the header for declarations.