Skip to content

Installation

This guide covers all installation options for IFClite.

Quick Start with create-ifc-lite

The fastest way to get started is using the create-ifc-lite CLI:

npx create-ifc-lite my-app
cd my-app
npm install
npm run parse sample.ifc

npx create-ifc-lite my-viewer --template react
cd my-viewer
npm install
npm run dev

npx create-ifc-lite my-viewer --template threejs
cd my-viewer
npm install
npm run dev

npx create-ifc-lite my-viewer --template babylonjs
cd my-viewer
npm install
npm run dev

npx create-ifc-lite my-backend --template server
cd my-backend
npm install
npm run server:start
npm run example sample.ifc

npx create-ifc-lite my-backend --template server-native
cd my-backend
npm install
npm run server:start

Available Templates

Template Description Use Case
basic (default) Minimal TypeScript parser project CLI tools, data extraction
threejs Three.js viewer (WebGL) Three.js / react-three-fiber apps
babylonjs Babylon.js viewer (WebGL) Babylon.js apps
react React + Vite + WebGPU viewer Full-featured web applications
server Docker-based Rust server Production deployments
server-native Native binary server Non-Docker environments

Package Manager Installation

npm / pnpm / yarn

# Core parsing (client-side)
pnpm add @ifc-lite/parser

# With rendering
pnpm add @ifc-lite/parser @ifc-lite/geometry @ifc-lite/renderer

# Server client SDK
pnpm add @ifc-lite/server-client

# IFC5 support
pnpm add @ifc-lite/ifcx

# Core parsing (client-side)
npm install @ifc-lite/parser

# With rendering
npm install @ifc-lite/parser @ifc-lite/geometry @ifc-lite/renderer

# Server client SDK
npm install @ifc-lite/server-client

# IFC5 support
npm install @ifc-lite/ifcx

# Core parsing (client-side)
yarn add @ifc-lite/parser

# With rendering
yarn add @ifc-lite/parser @ifc-lite/geometry @ifc-lite/renderer

# Server client SDK
yarn add @ifc-lite/server-client

# IFC5 support
yarn add @ifc-lite/ifcx

Available Packages

IFClite is published as many small packages under the @ifc-lite/* scope; install only what you need. The most commonly used:

Core Packages

Package Description
@ifc-lite/parser IFC STEP parsing (IFC2X3 / IFC4 / IFC4X3), entity extraction, schema registry
@ifc-lite/ifcx IFC5 (IFCX) JSON format parser
@ifc-lite/geometry Geometry processing (WASM bridge)
@ifc-lite/renderer WebGPU rendering pipeline
@ifc-lite/data Columnar data structures

Server Packages

Package Description
@ifc-lite/server-client Server SDK with caching and streaming
@ifc-lite/server-bin Native server binary wrapper

Additional Packages

Package Description
@ifc-lite/query Fluent query API
@ifc-lite/cache Binary cache format (.ifc-lite)
@ifc-lite/spatial Spatial indexing and culling
@ifc-lite/export Export (glTF, IFC STEP, Parquet, CSV)
@ifc-lite/cli ifc-lite terminal toolkit (see the CLI guide)
@ifc-lite/sdk High-level bim scripting SDK used by the CLI
@ifc-lite/ids IDS validation
@ifc-lite/bcf BCF collaboration files
@ifc-lite/mutations Property/attribute editing
@ifc-lite/clash Clash detection engine
@ifc-lite/drawing-2d 2D drawing generation

See the TypeScript API Reference for the documented API surface.

Server Installation

# Run the official container
docker run -p 3001:8080 ghcr.io/ltplus-ag/ifc-lite-server

# With persistent cache
docker run -p 3001:8080 -v ifc-cache:/app/cache ghcr.io/ltplus-ag/ifc-lite-server

# With environment configuration
docker run -p 3001:8080 \
  -e RUST_LOG=info \
  -e MAX_FILE_SIZE_MB=500 \
  -e WORKER_THREADS=8 \
  ghcr.io/ltplus-ag/ifc-lite-server

Option 2: Native Binary

# Install the server-bin package
npm install -g @ifc-lite/server-bin

# Start the server (downloads binary on first run)
ifc-lite-server

# Or use npx
npx @ifc-lite/server-bin

Environment Variables (the most common ones; the full list, including CORS_ORIGINS, IFC_SERVER_API_TOKEN and the memory/admission knobs, is in the Server guide):

Variable Default Description
PORT 8080 Server port
RUST_LOG info Log level (error, warn, info, debug)
MAX_FILE_SIZE_MB 500 Maximum upload size
WORKER_THREADS CPU cores Parallel processing threads
CACHE_DIR ./.cache Cache directory
REQUEST_TIMEOUT_SECS 300 Request timeout
INITIAL_BATCH_SIZE 100 Streaming initial batch
MAX_BATCH_SIZE 1000 Streaming max batch
CACHE_MAX_AGE_DAYS 7 Cache retention

Option 3: Build from Source

From the repository root (the server is a workspace member, so the binary lands in the root target/ directory):

cargo build --release -p ifc-lite-server
./target/release/ifc-lite-server

Rust Installation

Add to your Cargo.toml:

[dependencies]
ifc-lite-core = "19"
ifc-lite-geometry = "19"

Or install via cargo:

cargo add ifc-lite-core ifc-lite-geometry

Additional crates: ifc-lite-processing (streaming/entity scan), ifc-lite-export (glTF/IFC5 export), and ifc-lite-clash (clash detection).

Python Installation

Native geometry tessellation for Python (no Node, no WASM) is published as ifclite-geom:

pip install ifclite-geom

Prebuilt wheels ship for CPython 3.9+ on Linux (x86_64, aarch64), macOS (Apple silicon and Intel), and Windows (x64). See rust/python/README.md in the repository for the API.

Desktop App (Tauri)

ifc-lite no longer ships its own desktop app. The published @ifc-lite/* packages still support native desktop targets (via the platform bridge in @ifc-lite/geometry), so you can build your own native Tauri app on top of them. See the Building for Desktop guide for a step-by-step walkthrough.

If you need large IFC benchmark fixtures, fetch only the specific files you plan to use:

pnpm fixtures tests/models/ara3d/AC20-FZK-Haus.ifc

Prerequisites for a Desktop Build

Building a desktop app on the packages requires the Rust toolchain. See Tauri Prerequisites.

Desktop vs Web Comparison

Feature Web (WASM) Desktop (Native)
Parsing Single-threaded Multi-threaded (Rayon)
Memory WASM 4GB limit System RAM
File Access User upload only Direct filesystem
Startup Download WASM Instant
Large Files ~100MB practical limit 500MB+ supported

Building from Source

Prerequisites

  • Node.js 22.13+ or 24.x (engines in package.json)
  • pnpm 10 (pinned via packageManager: pnpm@10.8.1; corepack enable picks it up)
  • Rust toolchain (the pinned nightly in rust-toolchain.toml, installed automatically by rustup) - only for WASM builds (and your own desktop builds, if any)

Clone and Build

# Clone the repository (no Git LFS: fixtures are fetched on demand)
git clone https://github.com/LTplus-AG/ifc-lite.git
cd ifc-lite

# Install dependencies
pnpm install

# Build all packages (rebuilds WASM when wasm-pack is installed)
pnpm build

# Start the viewer
pnpm dev

Type-checking without Rust

The generated WASM type declarations are committed, so type-checking does not require Rust. The WASM runtime itself is gitignored: a fresh checkout must either build it with the pinned Rust toolchain and wasm-pack or run pnpm build:wasm:fetch to download the published bundle before the viewer can run or bundle. pnpm build rebuilds the runtime automatically when the Rust tools are installed.

Rebuilding WASM

If you modify Rust code:

# Install wasm-pack (if not already installed)
cargo install wasm-pack

# Rebuild WASM (outputs to packages/wasm/pkg)
pnpm build:wasm

CDN Usage

For quick prototyping without a build step:

<script type="module">
  import { IfcParser } from 'https://cdn.jsdelivr.net/npm/@ifc-lite/parser/+esm';

  const parser = new IfcParser();
  const response = await fetch('model.ifc');
  const buffer = await response.arrayBuffer();
  const store = await parser.parseColumnar(buffer);
  console.log('Entities:', store.entityCount);
</script>

For geometry processing with WASM, you must initialize the WASM module explicitly:

<script type="module">
  import { GeometryProcessor } from 'https://cdn.jsdelivr.net/npm/@ifc-lite/geometry/+esm';
  import initWasm from 'https://cdn.jsdelivr.net/npm/@ifc-lite/wasm/+esm';

  // Initialize WASM with explicit path (required for CDN)
  const wasmUrl = 'https://cdn.jsdelivr.net/npm/@ifc-lite/wasm/pkg/ifc-lite_bg.wasm';
  await initWasm({ module_or_path: wasmUrl });

  const processor = new GeometryProcessor();
  await processor.init();
  // ... process geometry
</script>

HTTP Server Required

CDN examples must be served from an HTTP server (not file://). Use npx serve . or python -m http.server.

Production Usage

For production applications, install packages locally rather than using CDN links.

Verifying Installation

Client-Side

import { IfcParser } from '@ifc-lite/parser';

const parser = new IfcParser();
const buffer = await fetch('model.ifc').then(r => r.arrayBuffer());
const store = await parser.parseColumnar(buffer);

console.log('Schema:', store.schemaVersion);
console.log('Entities:', store.entityCount);

Server Client

import { IfcServerClient } from '@ifc-lite/server-client';

const client = new IfcServerClient({ baseUrl: 'http://localhost:3001' });
const health = await client.health();

console.log('Server status:', health.status);

IFC5 Support

import { parseIfcx, detectFormat } from '@ifc-lite/ifcx';

const format = detectFormat(buffer); // 'ifc', 'ifcx', 'glb', or 'unknown'
if (format === 'ifcx') {
  const result = await parseIfcx(buffer);
  console.log('IFC5 entities:', result.entityCount);
}

Project Structure

After cloning the repository:

ifc-lite/
├── rust/                      # Rust/WASM backend
│   ├── core/                  # IFC/STEP parsing
│   ├── geometry/              # Geometry processing
│   ├── processing/            # Streaming / entity scan
│   ├── export/                # glTF / IFC5 export
│   ├── clash/                 # Clash detection
│   ├── ffi/                   # C FFI bindings
│   ├── python/                # Python wheel (ifclite-geom)
│   └── wasm-bindings/         # JavaScript API
│
├── packages/                  # TypeScript packages (@ifc-lite/*)
│   ├── parser/                # High-level IFC parser
│   ├── ifcx/                  # IFC5 (IFCX) parser
│   ├── geometry/              # Geometry bridge (WASM)
│   ├── renderer/              # WebGPU rendering
│   ├── cli/                   # Terminal toolkit
│   ├── sdk/                   # Scripting SDK
│   ├── viewer/                # @ifc-lite/viewer-core (CLI 3D viewer)
│   ├── server-client/         # Server SDK
│   ├── create-ifc-lite/       # Project scaffolding CLI
│   └── ...                    # query, data, spatial, export, ids, bcf, ...
│
├── apps/
│   ├── viewer/                # React web application
│   ├── viewer-embed/          # Embeddable viewer
│   ├── landing/               # Landing page
│   └── server/                # Rust HTTP server
│
└── docs/                      # Documentation (MkDocs)

Next Steps