Codex logo

Getting started

Setting Up a Project

Start a ModularCube application from an empty directory and get a working project running locally in a few steps.

This guide walks through the complete initial setup: preparing the environment, creating the project files, configuring the application, starting a local server, and creating your first component.

01 · Prerequisites

Prepare your environment

Before creating the project, make sure your development environment can serve ES modules over HTTP.

Required

Modern web browser

Use a modern browser with support for ES modules, Custom Elements, Shadow DOM, and standard browser APIs.

Required

Code editor

Use any editor capable of working with HTML, CSS, JavaScript, and JSON files.

Required

Local web server

The application must be served through HTTP so that JavaScript modules can be loaded by the browser.

02 · Create a new project

Create the project directory

Create a directory for your application and open it in your preferred code editor.

terminal
Step 1 · Create the project directory

Create a new directory for your ModularCube application.

mkdir my-project
folder_open
Step 2 · Enter the project directory

Move into the directory you just created.

cd my-project

Create the three files that form the initial application:

These files provide the document entry point, application initialization, and component configuration.

03 · Project structure

Organize the project

The application can begin with a few files at the project root and grow as components, services, modules, and assets are added.

Components can be grouped under src/components/, while additional directories can be introduced for services, reusable modules, and static assets.

04 · Application configuration

Configure the application

Open app.config.json and define the application root and the components that will be available to the application.

The application section defines app-body as the root component of the application.

info

Application root

Component registration priority

The application configuration defines the application root through its name property. However, when the same component is registered in the components list, the registered component takes priority and the application definition is not used to register it.

05 · Entry point

Set up index.html

The index.html file is the browser entry point. Add the ModularCube import map and load the initialization script.

Define the application content

The application root can receive its content in two ways. Choose the approach that best matches how the application is structured.

web

Document-oriented

Define content in index.html

Place the application content directly inside <app-body> using a <template>.

This approach keeps the page's content structure directly in the HTML document. The content is therefore part of the document source and can be understood by browsers, search engines, accessibility tools, and other systems that inspect the page document.

This is generally the preferred approach for content-oriented websites where the document structure and its content are important.

web_asset

Component-oriented

Load content from an HTML file

Keep the application root in index.html and define its content in a separate HTML file.

When the content is stored separately, the HTML file must be declared in the application's files.html.path configuration.

This approach keeps the document entry point minimal and moves the application's markup into the component's own HTML resource. It can be useful for application-style interfaces where the application content is treated as part of the component rather than as the primary document content.

06 · Initialization

Initialize ModularCube

Open init.js and initialize the framework using Dom.init().

When no configuration path is supplied, Dom.init() looks for app.config.json next to init.js.

07 · Run locally

Run your project locally

Start a local HTTP server from the project directory. For example, if Python is available on your system:

terminal
Step 1 · Start the local server

Start a local HTTP server from your project directory.

python3 -m http.server 8000
language
Step 2 · Open the application

Open the local application in your web browser.

http://localhost:8000
warning

Do not open index.html directly from the file system. The application should be served through HTTP so that browser module loading works correctly.