Skip to main content

First Steps

In this section, we will guide you through the initial steps of setting up your AxiSpark.js project. By following these instructions, you will have a basic project structure ready for development.

Language and Environment Setup​

Prerequisites​

Before you can start developing with AxiSpark.js, ensure you have the following tools installed:

  • Node.js (version 24 or higher)
  • npm (version 11 or higher)

Language​

The AxiSpark.js framework is built using TypeScript, a statically typed superset of JavaScript. TypeScript provides enhanced code quality, better tooling support, and improved maintainability for your applications.

The AxiSpark CLI will automatically set up your project with TypeScript, so you don't need to worry about configuring it manually.

Starting a New Project​

npm install -g @axisparkjs/cli
axispark new project-name

To scaffold a new AxiSpark.js project, you can use the AxiSpark CLI. This tool will help you set up a new project with the necessary structure and dependencies. Creating a new project with the CLI is recommended for first-time users.

Project Structure​

The project-name directory will be created, node modules and a few other boilerplate files will be installed, and a src/ directory will be created and populated with several core files.

  • src/index.bootstrap.ts: The main entry point of your application.
  • src/app.ts: The main application file where you can define your application logic.
  • ... Depending on the template you choose, additional files and directories may be created to help you get started quickly.

Bootstrap File​

The index.bootstrap.ts includes an async function, which will bootstrap our application:

index.bootstrap.ts
import { app } from './app';

const bootstrap = async () => {
    try {
        await app.init();
        await app.run();
    } catch (error) {
        console.error('Error during bootstrap:', error)
        throw error; // Rethrow the error to ensure the process exits with a non-zero status code
    } finally {
        await app.destroy();
    }
};

bootstrap().catch(() => {
    process.exit(1);
});

By default, if any unhandled errors occur during the bootstrap process, they will be logged to the console, and the application will exit with a non-zero status code. You can customize the error handling behavior as needed for your application.

Application File​

The app.ts file is where you can define your application logic, including plugins and other configurations. The app object is an instance of the AxiSpark.js application, which provides methods for initializing, running, and destroying the application.

app.ts
import { AxiSparkFactory } from '@axisparkjs/core';
import { ConsoleTransport, LogLevel, SimpleFormatter } from '@axisparkjs/logger';
import { ExamplePlugin } from './plugin';

export const app = AxiSparkFactory.create({
    name: 'Example App',
    basePath: __dirname,
    logTransports: [
        new ConsoleTransport({
            minLevel: LogLevel.Info,
            formatter: new SimpleFormatter()
        })
    ]
});

app.use(ExamplePlugin);

To create an AxiSpark.js application, we use the AxiSparkFactory.create() method, which takes an options object as a parameter. In this example, we set the application name, base path, and log transports. We also register an example plugin using the app.use() method.

The app.init() method initializes the application, setting up any necessary resources and configurations. The app.run() method starts the application, allowing it to handle requests and perform its intended functionality. Finally, the app.destroy() method cleans up any resources and performs necessary teardown operations when the application is shutting down.

Development​

Running the Application​

Once the installation process is complete, you can run the following command at your OS command prompt to start the application:

npm run build
npm run start

This command will execute the start script defined in your package.json file, which runs the compiled JavaScript code from the dist directory. The application will start, and you should see log messages indicating that it is running.

Running the Application in Development Mode​

Development mode allows you to make changes to your code and see the results without having to restart the application manually. To run the application in development mode, use the following command:

npm run dev

Linting and Formatting​

CLI templates does not include linting and formatting scripts by default. However, you can add them to your package.json file if you want to enforce code quality and consistency in your project.

It is recommended to use ESLint for linting and Prettier for code formatting. You can install them as development dependencies and add the following scripts to your package.json:

"scripts": {
    "lint": "eslint . --ext .ts",
    "prettier": "prettier ."
}

The lint script will run ESLint on all TypeScript files in your project, while the prettier script will format your code according to Prettier's rules. You can customize the configuration of both tools by creating their respective configuration files (.eslintrc.js and .prettierrc) in your project root.