Getting started
Requirements
Section titled “Requirements”Knowing TypeScript, CSS (or SCSS) and a little HTML will help, but you do not need them to get started.
If they are new to you, an AI assistant does the job very well: x4js gives it what it needs to write correct code, and you learn by reading what it produces. See Working with an AI assistant.
Tools:
- Node.js 24 or later is recommended.
- An editor that understands TypeScript, for example VS Code.
- For a desktop application: nothing more with the
electrontemplate; Go and the Wails command with thewailstemplate. The same application also runs in the browser.
There is nothing else to install: the x4js command line is part of the package. It handles the creation, the build and the live reload of your projects.
Create a project
Section titled “Create a project”npx x4js create my-appThe command creates the my-app folder from a template and installs its dependencies (--no-install not to install them). Five templates exist:
| Template | Content |
|---|---|
app |
Standard x4js application. This is the default. |
minimal |
Minimal x4js application. |
hosted |
x4js application ready for Vercel, Netlify or Cloudflare Pages. See Deploy. |
electron |
Desktop application, in an Electron window. |
wails |
Desktop application with Wails: the system side is written in Go, the result is a single executable. |
To pick one: npx x4js create my-app --template minimal. npx x4js templates prints the current list.
The electron and wails templates have their own layout and their own commands: their README.md describes them. The rest of this page follows the app template.
Run the project
Section titled “Run the project”cd my-appnpm run devThe project is built, then served locally. The address is printed in the terminal:
x4js 2.3.29mode devconfig C:\work\my-app\x4.config.jsonoutdir C:\work\my-app\binserver http://127.0.0.1:9000The templates choose port 9000 (dev.port in x4.config.json). Without that setting, x4js takes the first free port from 8000.
The page reloads each time a source file changes. A change that only touches CSS is applied without reloading.
What a project contains
Section titled “What a project contains”| File | Role |
|---|---|
package.json |
Dependency on x4js, and the dev and build scripts. |
x4.config.json |
Entry files, output folder, files to copy, port of the development server. |
tsconfig.json |
TypeScript settings. |
public/index.html |
The page, which loads main.js and main.css. The public folder is copied as it is to the output. |
src/main.ts |
The entry point of the application. |
src/main.scss |
The styles of the application. |
src/icons.ts, src/assets/ |
The SVG icons of the application (not in the minimal template). |
src/global.d.ts |
The type of imported .svg files. |
A first interface
Section titled “A first interface”Everything starts in src/main.ts. Here is a complete application: a label, and a button that changes it.
import { Application, Button, Label, VBox } from 'x4js';
import "./main.scss";
class App extends Application { constructor( ) { super( );
const status = new Label( { text: "Ready" } );
this.setMainView( new VBox( { content: [ status, new Button( { label: "Run", click: ( ) => status.setText( "Done" ) } ), ] } ) ); }}
new App( );The application derives from Application and sets its main view once, in its constructor.
Save the file: the page updates by itself.
Build for production
Section titled “Build for production”npm run buildThe result is written to the bin folder, minified and without source maps. That folder is emptied before each build: do not keep hand-written files in it.
Deploy
Section titled “Deploy”A built x4js application is a static site: any host can serve the bin folder.
The hosted template is the app template plus the configuration for Vercel and Netlify. The Deploy page details publishing on Vercel, Netlify, Cloudflare Pages or another host.
Going further
Section titled “Going further”- Deploy: publish the application on a host.
- Interface design: split a screen into containers.
- Components and events: write your own views.
- Command line: every option of
x4jsand the keys ofx4.config.json. - API reference.