Quickstart
This section covers getting started with the framework, installing the required packages, and setting up a basic project.
Installing the packages
There are two ways of getting started, manually, or via our CLI (recommended).
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:
IMPORTANT
Please be aware, if you have the package installed already globally, you may need to either remove it or update it to the latest version.
bun create @sodacore
bun create @sodacore@beta
bun create @sodacore@alphaThis 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 concepts page to get familiar with how the framework works.
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.
TIP
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 initEnsure 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
DOMlib, 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/httpIf you want to use the latest beta or alpha version, then use the
@betaor@alphatag, i.e.bun add @sodacore/core@beta. Please note while we are still in alpha, just use the@alphatag, 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.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=8080Setup 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": "ENV=dev bun run ./src/main.ts",
"start": "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 devYou can now go to your localhost at the port you defined, and you should see the message Hello, Sodacore!.
Next Steps
Congratulations, you have your first Sodacore project up and running!
To get started, we suggest reading up on the framework concepts and then looking at the packages to see what you can do with the framework.
