Babylon.js Project Scaffolding CLI

9.3.3 · active · verified Tue Apr 21

create-babylonjs is a command-line interface (CLI) tool designed to quickly scaffold new Babylon.js projects. It simplifies project setup by offering choices for module format (ES6 for tree-shaking or UMD for global `BABYLON` namespace), language (TypeScript or JavaScript), and bundler (Vite, Webpack, Rollup, or no bundler for CDN-only). The tool ensures a ready-to-run project that includes a starter scene, glTF model loading, environment lighting, and proper side-effect imports for optimized ES6 builds. Currently at version 9.3.3, it tracks the rapid development cycle of the Babylon.js core library, which typically sees new minor versions released weekly and major versions annually. This CLI is crucial for developers seeking a streamlined entry into Babylon.js development without the overhead of manual project configuration.

Common errors

```
Module not found: Error: Can't resolve '@babylonjs/core'
```
cause Incorrect or incomplete import path in an ES6 module project, often caused by trying to import from the root package instead of a deep path.

fix Ensure imports specify the full path to the module, e.g., `import { Engine } from '@babylonjs/core/Engines/engine';`.
```
BABYLON is not defined
```
cause Attempting to access the `BABYLON` global object in a project configured for ES6 modules without a UMD import, or in a CDN-based project where the `babylon.js` script tag is missing or loaded incorrectly.

fix If using UMD, ensure `import * as BABYLON from 'babylonjs';` is present. If using CDN, verify the `babylon.js` script tag is correctly placed in `index.html`.
```
Uncaught TypeError: scene.createDefaultCamera is not a function
```
cause Missing the necessary side-effect import for Babylon.js helper functions or specific features like `createDefaultCamera` or `createDefaultEnvironment`.

fix Add `import '@babylonjs/core/Helpers/sceneHelpers';` to the top of your main scene file to register these helper functions.

Warnings

breaking Babylon.js core library, used by generated projects, upgraded to TypeScript 6.0 in version 9.1.0. Older projects upgrading Babylon.js manually might encounter type conflicts if their TypeScript version is not updated accordingly.
Fix: Ensure your project's `tsconfig.json` targets TypeScript 6.0 or higher when using Babylon.js 9.1.0 and later.
gotcha To leverage tree-shaking and optimize bundle size in ES6 projects, always use deep imports (e.g., `import { Engine } from '@babylonjs/core/Engines/engine';`) instead of root imports (e.g., `import { Engine } from '@babylonjs/core';`).
Fix: Update imports to point directly to the module file for each component, e.g., `import { Scene } from '@babylonjs/core/scene';`.
gotcha Forgetting to include side-effect imports for essential features like glTF loaders (`import '@babylonjs/loaders/glTF';`) or certain materials (`import '@babylonjs/core/Materials/standardMaterial';`) will lead to runtime errors when attempting to use those features.
Fix: Add the specific side-effect import for each loader or material package required by your scene.
gotcha The 'None' bundler option generates a CDN-only project without `npm` dependencies or a development server. It is suitable for simple experiments or learning but lacks modern development features like hot-reloading or optimized production builds.
Fix: For serious development, choose Vite, Webpack, or Rollup during project creation. For the CDN-only template, open `index.html` directly in a browser to run the application.
breaking Babylon.js 9.0 introduced significant updates to rendering, including major changes to how main materials generate WGSL shader code with WebGPU. Custom shaders or advanced material plugins might require adjustments.
Fix: Review Babylon.js 9.0 documentation for `MaterialPlugin` updates and changes to shader generation, particularly if using WebGPU or custom material extensions.

Install

npm install create-babylonjs npm
yarn add create-babylonjs yarn
pnpm add create-babylonjs pnpm

Imports

Engine, Scene
wrong:
```
import { Engine, Scene } from '@babylonjs/core';
```
correct:
```
import { Engine, Scene } from '@babylonjs/core/Engines/engine';
import { Scene } from '@babylonjs/core/scene';
```
For ES6 modules and effective tree-shaking, always use deep imports from `@babylonjs/core` to pull in only necessary components. Importing from the root package will include the entire library, negating tree-shaking benefits.
GLTF Loader
wrong:
```
SceneLoader.AppendAsync(file, scene); // Errors without loader import
```
correct:
```
import '@babylonjs/loaders/glTF';
```
Loaders like glTF are registered via side-effect imports. This line must be present to enable glTF model loading functionality at runtime in ES6 projects.
BABYLON (UMD)
wrong:
```
const BABYLON = require('babylonjs'); // Incompatible with modern bundlers in ESM projects
```
correct:
```
import * as BABYLON from 'babylonjs';
```
For UMD (CommonJS) projects or when targeting older environments, the entire Babylon.js library is imported into a global `BABYLON` namespace. This is less common in new, bundled ES6 projects.

Quickstart

Initializes a new Babylon.js project using the CLI, installs project dependencies, and starts the local development server.

npm create babylonjs
cd my-babylonjs-app
npm install
npm run dev

view raw JSON →