Quickstart

This section covers getting started with the framework, installing the required packages, and setting up a basic project.

• Installing the packages
  • CLI Tool (@sodacore/create)
  • Manually
• Start the framework
• Next Steps

Installing the packages

There are two ways of getting started, manually, or via our CLI (recommended).

Quick note, you can technically use any package manager you want, but consider we are using the bun runtime, all examples will use the bun package manager.

CLI Tool (@sodacore/create)

To get started with the CLI tool, you can simply run the following:

bun create @sodacore
bun create @sodacore@beta # for latest beta version.
bun create @sodacore@alpha # for latest alpha version. (use until we hit v1)

This will install and launch the command line, it simply asks you about your project, and then installs the packages and writes the files, it will also modify the directory to correctly reflect the Sodacore project structure.

Note because the project is kept as part of a monorepo, the @sodacore instead of just sodacore tells Bun to use the @sodacore/create package from the monorepo, instead of create-sodacore.

We recommend this way due to simplicity, see below:

Once you have done this, you can skip right to the Packages section to see what packages you can install and learn how to use the different core plugins.

Manually

Doing it manually takes a few more steps, but we will guide you through it.

Setting up your project.

To start with find a home (folder) for your project, once you have done this, ensure your Bun install is up to date.

If you haven't already install Bun, you can go to their website and follow the instructions. To update Bun, simply call bun upgrade.

Let's initialise a Bun project, you can do this by running:

bun init

Ensure you select the "Blank" template.

This will initialise the current project folder, from here, we need to tweak the tsconfig.json file due to our use of legacy decorators, add these to the compilerOptions section:

{
	"compilerOptions": {

		// Enable latest features
		"lib": ["ESNext"],
		"target": "ESNext",
		"module": "ESNext", 
		"moduleDetection": "force",
		"jsx": "react-jsx",
		"allowJs": true,
		"outDir": "./dist", 

		// Bundler mode
		"moduleResolution": "bundler",
		"verbatimModuleSyntax": true,
		"allowImportingTsExtensions": true,
		"noEmit": false, 
		"noEmit": true, 

		// Best practices
		"strict": true,
		"skipLibCheck": true,
		"noFallthroughCasesInSwitch": true,
		"noUncheckedIndexedAccess": true,
		"noImplicitOverride": true,

		// Some stricter flags (disabled by default)
		"noUnusedLocals": true,
		"noUnusedParameters": false,
		"noPropertyAccessFromIndexSignature": false,

		// Build.
		"declaration": true, 
		"declarationMap": true, 
		"esModuleInterop": true, 

		// Decorators.
		"experimentalDecorators": true, 
		"emitDecoratorMetadata": true, 
		"useDefineForClassFields": false, 
	},
	"include": [ 
		"src/**/*.ts", 
		"src/**/*.tsx", 
	], 
}

You can see ours here: tsconfig.json, I would also suggest removing the DOM lib, as this is a server-side project.

Lastly we suggest deleting the index.ts file that is at the root, and make yourself a src folder.

Installing the packages

You will want to install the core packages, we shall also include the HTTP plugin as well so you have a usable example, as the core framework is not a web framework and rather than a "handler" for other services and code.

bun add @sodacore/di @sodacore/core @sodacore/http

If you want to use the latest beta or alpha version, then use the @beta or @alpha tag, i.e. bun add @sodacore/core@beta. Please note while we are still in alpha, just use the @alpha tag, as we are not yet at v1.0.0.

Create your entry file

Once you're setup, you can easily get started with the framework by creating yourself an entry file: ./src/main.ts and then put the following code in it:

All documentation will be written in TypeScript going forward.

import { Application } from '@sodacore/core';
import { env } from 'bun';
import { resolve } from 'node:path';
import process from 'node:process';
import HttpPlugin from '@sodacore/http';

// Initialise application.
const app = new Application({
	autowire: true, // Autowiring will automatically register your controllers and parts of your app.
	basePath: env.SODACORE_ENV === 'prod' // This part deals with production and compilation.
		? resolve(process.cwd(), './dist')
		: undefined,
});

// Install the HTTP plugin.
app.use(new HttpPlugin({
	port: env.HTTP_PORT ? parseInt(env.HTTP_PORT, 10) : 3000, // Default to 3000 if not set.
}));

// Start the application and catch any errors.
app.start().catch(console.error);

All packages will define their configuration options in their respective documentation page.

Setup your environment file.

You can create a .env file in the root of your project, and add the following:

HTTP_PORT=8080

Setup your package.json

You should have a package.json that is created let's add the required launch scripts:

{
	"name": "sodacore-project",
	"module": "index.ts",
	"type": "module",
	"private": true,
	"devDependencies": {
		"@types/bun": "latest"
	},
	"peerDependencies": {
		"typescript": "^5"
	},
	"scripts": { 
		"dev": "SODACORE_ENV=dev bun run ./src/main.ts", 
		"start": "SODACORE_ENV=prod bun run ./dist/main.js", 
		"build": "rm -rf ./dist && bun tsc --project ./tsconfig.json"
	} 
}

Create your first controller

Inside of ./src/controller/ create a new file called HelloController.ts, and add the following code:

import { Controller, Get } from '@sodacore/http';

@Controller('/')
export class HelloController {

	@Get('/')
	public index() {
		return 'Hello, Sodacore!';
	}
}

Start the framework

You can start the framework by doing:

bun dev

You can now go to your localhost at the port you defined, and you should see the message Hello, Sodacore!.

Next Steps

Congratulations! You have now set up a basic Sodacore application with an HTTP plugin and a simple controller. You can keep following the guide that will explain most of the features of the framework and packages, or you can refer to the package specific documentation for more details on how to use them. You can find the packages here: Packages.