Getting Started

• Setting up your project.
• Installing the packages
• Create your entry file
• Setup your environment file.
• Setup your package.json
• Create your first controller
• Start the framework
• Next Steps

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.