Quickstart

This guide will help you set up a new Orionjs project quickly by using our example repository.

Prerequisites

Bun (v1.0 or later) — the default runtime
MongoDB (local instance or connection string)
Basic knowledge of TypeScript

Node.js (v22+) is also supported. See Using Node.js instead of Bun below.

Using the Example Project

The fastest way to get started with Orionjs is to use our example project. It provides a fully functioning application that demonstrates the core features and best practices.

# Clone the starter repository
git clone https://github.com/orionjs/orionjs-services-starter

# Navigate to the project directory
cd orionjs-services-starter

# Install dependencies
bun install

Project Structure

The example project follows the standard Orionjs structure:

example/
├── app/                # Main application code
│   ├── config/         # Application configuration
│   ├── exampleComponent/ # Example component implementation
│   ├── env.d.ts        # Environment type definitions
│   └── index.ts        # Application entry point
├── .env.local.yml      # Environment variables
├── package.json        # Project dependencies
├── start.sh            # Start script for local development
└── tsconfig.json       # TypeScript configuration

For a more detailed explanation of the project structure, check out our Project Structure guide.

Running the Application

Before running the application, make sure you have MongoDB running. The example project is configured to connect to mongodb://localhost:3003/example by default. You can start the application in development mode using:

# Using the provided start script
./start.sh

# Or manually
export ORION_ENV_SECRET_KEY=pk+uJ3wTEZxuDWKF6zdeypUzQQNkKE3i+bnfHe6g+RU=
export ORION_ENV_FILE_PATH=.env.local.yml
export PORT=3010
bunx orion dev

The application will start with Bun’s built-in watch mode. Any file changes will automatically restart the server. You can access it at http://localhost:3010.

Using Node.js Instead of Bun

If you prefer to use Node.js, pass the --node flag to any CLI command:

# Dev mode with Node.js (uses tsx watch)
bunx orion dev --node

# Production mode with Node.js
bunx orion prod --node

When using Node.js you’ll also need tsx installed in your project.

Key Features of the Example

The example project demonstrates several key features of Orionjs:

Component-based architecture
Configuration management
Environment variable handling
TypeScript integration
Project structure best practices

Learning from the Example

We recommend exploring the example code to understand:

How components are organized and structured
Configuration patterns for different environments
The integration between different Orionjs modules
How to set up and manage environment variables securely

Customizing the Example

After getting the example running, you can start customizing it:

Create your own components following the same structure
Add or modify HTTP controllers for REST endpoints
Implement GraphQL resolvers and models
Set up background jobs or event-driven features with Echoes
Configure database connections for your specific needs

Next Steps

After exploring the example project, check out our other documentation sections to learn more about specific aspects of Orionjs:

Happy coding with Orionjs!

Get Started

Essentials

Controllers

Other Modules

Prerequisites

Using the Example Project

Project Structure

Running the Application

Using Node.js Instead of Bun

Key Features of the Example

Learning from the Example

Customizing the Example

Next Steps

​Prerequisites

​Using the Example Project

​Project Structure

​Running the Application

​Using Node.js Instead of Bun

​Key Features of the Example

​Learning from the Example

​Customizing the Example

​Next Steps

Prerequisites

Using the Example Project

Project Structure

Running the Application

Using Node.js Instead of Bun

Key Features of the Example

Learning from the Example

Customizing the Example

Next Steps