​
Introduction

OrbitKit is setup as a monorepo, which comes with three applications and many packages, here is the codebase structure:

apps
├── docs # Documentation website with Mintlify
├── marketing # Marketing website with Astro
└── web # Web application with Next.js
packages
  ├── assets # Shared assets library for example, images, fonts, etc.
  ├── auth # Auth package to handle authentication.
  └── config # Config directory hosts tools config packages.
    ├── eslint # ESLint config package.
    ├── storybook # Storybook config package.
    ├── tailwind # Tailwind preset package.
    ├── tsconfig # TSConfig presets library to configure TypeScript.
    └── vite # Shared vite config.
  ├── core # Empty package for business logic.
  ├── db # Database handling package with Drizzle ORM.
  ├── env # Environment variables validation using t3-env.
  ├── ui # Shadcn UI library with Storybook.
  └── utils # misc utilities.

We will go more in detail about every aspect of orbitkit later on, but this should give you a good idea of what to expect.

​
Prerequisites

Before you begin, ensure you have met the following requirements:

  • You have Node v20 and Pnpm v8 installed on your machine. We recommend you using Volta to manage your Node versions and you can use it as well for pnpm experimentally.

That is actually pretty much all you need!

​
Installation

With all that being said, we are ready to start using Orbitkit! We firstly need to clone it down to your machine and then we can install dependencies, configure environment variables and run it!

​
Configuring environment variables

You will need to set-up some environment variables in a .env.local file in the apps/web directory. We provide an example file in apps/web/.env.example that you can copy over and input the values.

# Copy the .env.example file into a .env.local file.
cp ./apps/web/.env.example ./apps/web/.env.local

Here is how you can obtain each of the required values:

​
Database

The database that OrbitKit uses is Neon PostgreSQL. You should create a free account and input the database url given to you on the dashboard to be the value of the DATABASE_URL environment variable.

Make sure that the DATABASE_URL ends with ?sslmode=require.

​
Uploadthing

Uploadthing is the service of choice in OrbitKit for file uploads, you should create an account and input the api keys into the .env.local File.

​
Unkey (optional)

Unkey is the service of choice in OrbitKit for rate limiting, it is however optional as that if the UNKEY_ROOT_KEY or UNKEY_NAMESPACE variables are not supplied, no rate limiting is applied.

To obtain this key, head over to your unkey dashboard and create a new ratelimit namespace, then in your settings, create a new root key, that will be the value of your environment variable.

As for the namespace that you have created, you will need to put that as the value of the UNKEY_NAMESPACE environment variable.

​
OAuth

OrbitKit currently ships with two authentication providers, Google and Github. You will need to create an OAuth application on the respective platforms and input the values into the .env.local file.

Based on the environment variables set, authentication will be provided. For example, setting AUTH_GITHUB_ID and AUTH_GITHUB_SECRET will make it so that Github OAuth is then activated on the web application. The same is true for Google OAuth.

​
Reset changelog and versions

When you first clone the repository, you should reset the changelog and versions to start fresh. You can do so by running the following commands:

# Reset changelog - this will remove all the changelog.md files in the packages
pnpm reset:changelog

# Reset package versions - this will reset the versions of all the packages to 0.1.0
pnpm reset:versions

​
Running the project

Now that you have set up the environment variables, you can run the project!

pnpm turbo dev

This command will apply the necessary database migrations and start the development tasks on all of the apps & packages.

You should be able to access the web app on http://localhost:3000, the marketing website on http://localhost:4321 and the documentation website on http://localhost:3002.

For more info about the commands available to you, you can check out the Commands page.

IntroductionCommands