
## Overview

`create-babylonjs` is the official Babylon.js project scaffolder. Running a single command launches an interactive CLI that asks you a few questions and then generates a fully configured, ready-to-run project. No manual wiring of bundlers, TypeScript configs, or Babylon.js imports required.

## Quick Start

```bash
npm create babylonjs
```

Then follow the on-screen prompts, and start your app:

```bash
cd my-babylonjs-app
npm install
npm run dev
```

You can also pass a project name directly to skip the first prompt:

```bash
npm create babylonjs my-scene
```

## What the CLI Asks

The CLI walks you through four choices:

| Prompt            | Options                                                                                    |
| ----------------- | ------------------------------------------------------------------------------------------ |
| **Project name**  | Any name (defaults to `my-babylonjs-app`)                                                  |
| **Module format** | ES6 (`@babylonjs/core` — tree-shakeable) or UMD (`babylonjs` — global `BABYLON` namespace) |
| **Language**      | TypeScript or JavaScript                                                                   |
| **Bundler**       | Vite, Webpack, Rollup, or None (CDN script tags — UMD only)                                |

<Alert severity="info" title="CDN-only option" description="The 'None' bundler option is only available when UMD is selected as the module format. It generates a single index.html file with CDN script tags — no npm install or build step needed." />

## Generated Project

Every scaffolded project includes:

- A starter scene that loads a glTF model (`boombox.glb`) with environment lighting
- `SceneLoader.AppendAsync` for async model loading
- `scene.createDefaultCamera()` to automatically frame the loaded model
- `scene.createDefaultEnvironment()` for a skybox, reflective ground, and image-based lighting (IBL)
- A render loop with canvas resize handling
- `package.json` with `dev`, `build`, and `build:prod` scripts

### ES6 Template

Uses tree-shakeable imports from `@babylonjs/core` and `@babylonjs/loaders`, along with the required side-effect imports for tree-shaken builds:

```typescript
import { Engine } from "@babylonjs/core/Engines/engine";
import { Scene } from "@babylonjs/core/scene";
import { SceneLoader } from "@babylonjs/core/Loading/sceneLoader";
import "@babylonjs/core/Loading/loadingScreen";
import "@babylonjs/core/Helpers/sceneHelpers";
import "@babylonjs/core/Materials/standardMaterial";
import "@babylonjs/core/Materials/PBR/pbrMaterial";
import "@babylonjs/core/Materials/Textures/Loaders/envTextureLoader";
import "@babylonjs/loaders/glTF";
```

### UMD Template

Uses the `babylonjs` and `babylonjs-loaders` packages with the global `BABYLON` namespace:

```typescript
import * as BABYLON from "babylonjs";
import "babylonjs-loaders";
```

### CDN-only Template (No Bundler)

A single `index.html` with `<script>` tags — no `npm install` required:

```html
<script src="https://cdn.babylonjs.com/babylon.js"></script>
<script src="https://cdn.babylonjs.com/loaders/babylonjs.loaders.min.js"></script>
```

<Alert severity="warning" title="CDN in production" description="The CDN is intended for learning and prototyping. For production applications, serve Babylon.js from your own CDN or bundle it with your application." />

## Template Matrix

The combination of module format, language, and bundler determines the generated files:

| Module Format | Language | Bundler                 | Generated Files                                                                                     |
| ------------- | -------- | ----------------------- | --------------------------------------------------------------------------------------------------- |
| ES6           | TS or JS | Vite                    | `src/index.{ts,js}`, `vite.config.{ts,js}`, `index.html`, `package.json`, `tsconfig.json` (TS only) |
| ES6           | TS or JS | Webpack                 | `src/index.{ts,js}`, `webpack.config.js`, `index.html`, `package.json`, `tsconfig.json` (TS only)   |
| ES6           | TS or JS | Rollup                  | `src/index.{ts,js}`, `rollup.config.mjs`, `index.html`, `package.json`, `tsconfig.json` (TS only)   |
| UMD           | TS or JS | Vite / Webpack / Rollup | Same structure, but uses `babylonjs` + `babylonjs-loaders` packages                                 |
| UMD           | JS       | None                    | `index.html` only (CDN `<script>` tags)                                                             |

## Bundler Configurations

Each bundler template includes a `dev` script for local development and a `build:prod` script for production:

| Bundler | Config File                         | Dev Command                                    |
| ------- | ----------------------------------- | ---------------------------------------------- |
| Vite    | `vite.config.ts` / `vite.config.js` | `npm run dev`                                  |
| Webpack | `webpack.config.js`                 | `npm run dev` (webpack-dev-server)             |
| Rollup  | `rollup.config.mjs`                 | `npm run dev` (rollup with watch + livereload) |
| None    | —                                   | Open `index.html` directly in a browser        |

## Production Build

All bundler-based templates include a `build:prod` script that creates an optimized production bundle:

```bash
npm run build:prod
```

| Bundler | Output           | Preview                                         |
| ------- | ---------------- | ----------------------------------------------- |
| Vite    | `dist/`          | `npm run preview`                               |
| Webpack | `dist/`          | Serve `dist/` with any static HTTP server       |
| Rollup  | `dist/bundle.js` | Open `index.html` (references `dist/bundle.js`) |

Deploy the contents of `dist/` (or the project root for CDN-only) to any static hosting provider.

## Choosing a Module Format

If you are starting a new project, **ES6 is recommended**. It enables tree-shaking — only the parts of Babylon.js your code actually uses are included in the bundle, keeping the final size as small as possible.

**UMD** is the better choice when:

- You want to use Babylon.js via `<script>` tags without a bundler (CDN-only option)
- You are copying examples directly from the Babylon.js documentation (most doc examples use the `BABYLON.*` namespace)
- You need a quick prototype without setting up a build pipeline

See [ES6 / NPM Support](/setup/frameworkPackages/es6Support) and [UMD / NPM Support](/setup/frameworkPackages/npmSupport) for a deeper comparison.

## Next Steps

After scaffolding, the generated `src/index.ts` (or `.js`) is your entry point. From there you can:

- Replace the sample model load with your own assets
- Add meshes, lights, cameras, and materials
- Explore the [Babylon.js documentation](https://doc.babylonjs.com) and [Playground](https://playground.babylonjs.com) for inspiration
- Install additional Babylon.js packages (`@babylonjs/gui`, `@babylonjs/inspector`, etc.) with `npm install`



## Available Packages

We offer the following packages via CDN, NPM, and ES6. It is important that you choose only one of these delivery methods for your project; mixing any two of them will ensure failure.

The packages available are listed below.

The core **babylonjs**, which is necessary for all and sufficient for many projects, plus:

* babylonjs-materials - _A collection of Babylon-supported **advanced** materials._
* babylonjs-loaders - _All of Babylon's official loaders (OBJ, STL, glTF)._
* babylonjs-post-process - _Babylon's post processes._
* babylonjs-procedural-textures - _Officially supported procedural textures_.
* babylonjs-serializers - _Scene / mesh serializers._
* babylonjs-gui - _Babylon.js GUI._
* babylonjs-inspector - _Babylon.js inspector._
* babylonjs-viewer - _The stand-alone Babylon.js Viewer._

## History of Package Delivery

In the early days the framework was written in JavaScript and the common way of consuming a JavaScript framework was to load it in a script tag in your HTML and populate a global namespace. Hence the use of BABYLON as the namespace as, for example, in

```javascript
var scene = new BABYLON.Scene(engine);
var camera = new BABYLON.FreeCamera("camera1", new BABYLON.Vector3(0, 5, -10));
var light = new BABYLON.HemisphericLight("light", new BABYLON.Vector3(0, 1, 0));
```

The framework was originally available as a single JavaScript package to download from GitHub, and away you went. While this approach has a very clear upside—ease of use—it also has many downsides. As the package grew larger and larger over time, the framework became harder to maintain, and attempts to provide a way to minimize the package size were only partly successful. To overcome these issues, a change to developing in TypeScript and using NPM was introduced to the framework. As backward compatibility is an important principle of Babylon.js, the current JavaScript packages are still available from the Babylon.js CDN and can be directly accessed or downloaded for local use.

The use of npm meant that developers could include Babylon.js in their build tools. By version 3, module support had been added using CommonJS and then moved to UMD (Universal Module Definition). The good thing about our UMD package is that it supports one of Babylon.js’ cornerstones: backward compatibility. Namespaces worked, packages could still be included in a script tag, and for those who wanted it, projects could be written in TypeScript and compiled to JavaScript. Everybody was happy. Then along came ES6.

ES6 provides better dependency management, better syntax, and better code structure. And with it comes one of its wonderful side effects: take only what you need. There is no need to consume the entire Babylon.js package if you just want to show a sphere in a skybox. Welcome, tree shaking! Writing your project in TypeScript is of course supported. However, ES6 has a few hurdles that need to be jumped over just to get it to work. You will probably need a bundler. You will probably need a (custom) build process. You will probably need to compile it to ES5 for cross-browser support.

Babylon.js’s codebase has gradually moved from an older namespace-based syntax to a modern import-based syntax. A main issue with that was backward compatibility. A future-safe architecture is always a hard task and apparently the older versions of Babylon.js were not entirely that. In some cases, we had circular dependencies. In some cases, we had side-effect (code running when the script is loaded), which is discouraged when using (pure) es6 modules.


## Choosing
What should you use?

Well, as always, that depends. UMD is still faster for rapid prototyping. The Babylon.js playground, for example, still uses the UMD packages (and the global BABYLON namespace). On the other hand, if you start a new project and want to bring a bit of structure, better architecture and smaller package size, I always recommend ES6.

UMD “just works”, mainly because it is still using the most basic browser functionalities. It is also guaranteed to work on any browser with WebGL support (yes IE11, I am looking at Safari). Don’t want to use npm? You don’t have to.

ES6 does not populate the global namespace, so no more BABYLON.* support. This might cause (your) legacy work to stop working, or might present some compatibility issues with our documentation website, which, for the sake of consistency, mostly uses the BABYLON namespace in code examples. So if you want to just copy examples from the doc page without the need to (sometimes) change them, use UMD.

But whatever you do, choose one of them. Most of the time, when we have a forum question about build issues, it is because of mixing the two module flavors.




## Minimal HTML Template

<Alert severity="warning" title="Warning" description="The CDN should not be used in production environments. The purpose of our CDN is to serve Babylon packages to users learning how to use the platform or running small experiments. Once you've built an application and are ready to share it with the world at large, you should serve all packages from your own CDN."/>

```html
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">

    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
        <title>Babylon Template</title>

        <style>
            html, body {
                overflow: hidden;
                width: 100%;
                height: 100%;
                margin: 0;
                padding: 0;
            }
            #renderCanvas {
                width: 100%;
                height: 100%;
                touch-action: none;
            }
        </style>

        <script src="https://cdn.babylonjs.com/babylon.js"></script>

    </head>

   <body>

	<canvas id="renderCanvas"></canvas>

	<script>
        const canvas = document.getElementById("renderCanvas"); // Get the canvas element
        const engine = new BABYLON.Engine(canvas, true); // Generate the BABYLON 3D engine
        const createScene = function () {
            // Creates a basic Babylon Scene object
            const scene = new BABYLON.Scene(engine);
            // Creates and positions a free camera
            const camera = new BABYLON.FreeCamera("camera1", 
                new BABYLON.Vector3(0, 5, -10), scene);
            // Targets the camera to scene origin
            camera.setTarget(BABYLON.Vector3.Zero());
            // This attaches the camera to the canvas
            camera.attachControl(canvas, true);
            // Creates a light, aiming 0,1,0 - to the sky
            const light = new BABYLON.HemisphericLight("light", 
                new BABYLON.Vector3(0, 1, 0), scene);
            // Dim the light a small amount - 0 to 1
            light.intensity = 0.7;
            // Built-in 'sphere' shape.
            const sphere = BABYLON.MeshBuilder.CreateSphere("sphere", 
                {diameter: 2, segments: 32}, scene);
            // Move the sphere upward 1/2 its height
            sphere.position.y = 1;
            // Built-in 'ground' shape.
            const ground = BABYLON.MeshBuilder.CreateGround("ground", 
                {width: 6, height: 6}, scene);
            return scene;
        };
        const scene = createScene(); //Call the createScene function
        // Register a render loop to repeatedly render the scene
        engine.runRenderLoop(function () {
                scene.render();
        });
        // Watch for browser/canvas resize events
        window.addEventListener("resize", function () {
                engine.resize();
        });
	</script>

   </body>

</html>
```

<a href="https://raw.githubusercontent.com/BabylonJSGuide/Tiled/master/basic1/index.zip" download="index.zip">Download</a> the template file that uses Babylon.js from the CDN.   
<br />
<a href="https://raw.githubusercontent.com/BabylonJSGuide/Tiled/master/basic2.zip" download="basic template">Download</a> the template file containing a local version of Babylon.max.js

## Description

**Color Key to Babylon.js Sections**

![Webpage Key](/img/quickstart/htmlkey.webp)

**HTML with Babylon.js Sections in Color**

![Basic Webpage](/img/quickstart/htmlbjs.webp)

## Playground to Download From
Use the &#x2913; button to download the template from the Playground.

<Playground id="#WJXQP0" title="Basic Playground" description="CreateScene Playground Template." />  


# Developing With and For Babylon.js

For those of you who want to know more about the organization and structure of Babylon.js so you can either build well-structured projects of your own or contribute to it, you have come to the right place. Here you will find where to obtain Babylon.js in full or just the modules you need to import into your JavaScript or TypeScript application.

Even the best developers need help from time to time, and the Babylon.js forum is there to help. To make the best use of the forum, check out the first page of this section.

Contributions can come in many forms. Answering questions on the forum is a useful contribution. Others may spot spelling errors in the documentation or find ways to improve it. Potential contributors to Babylon.js come from many different backgrounds. For some of you, version control systems, repositories, package managers, and task runners are second nature, and all you need to know are the requirements set by the Babylon.js core team for a pull request to be accepted. For others, especially those who just want to explore the world of 3D, they can feel like a series of confusing hurdles. This section therefore contains details that many of you can ignore as obvious. For others, those details may be the difference between making a contribution and not making one.



Useful templates to aid in development.


## Getting Your Babylon.js Web Project Set Up
This section provides guidance on the workflow required to create a 3D web app, from getting started by downloading a complete webpage from a simple playground to building a large application using an IDE and other development frameworks and packages.

Workflow

Getting Your Babylon.js Web Project Set Up

Coming next

Scaffold a Babylon.js Project with create-babylonjs

Use the create-babylonjs CLI to generate a ready-to-run Babylon.js project with your choice of module format, language, and bundler.

Starter HTML Template

Get started with the workflow, from a simple webpage to a complete app with an IDE and development frameworks.

A Range of Templates and Template Repositories

A category holding templates and repositories

Obtaining Babylon.js Packages

Different ways to obtain the framework packages.

Developing With and For Babylon.js

Dive into the amazing world of contributing to the Babylon platform.