Manually Installing Factor

Creating a Factor project from scratch is easy, only a project folder and a package.json file are required. Create an empty directory to start:

mkdir <project-name>
cd <project-name>

Adding Core Dependency

Next just add @factor/core as a dependency to your project. This will install the terminal CLI and all required tooling:

npm add @factor/core

Add Main File

Next just add a main file in your project. Typically this is called index.ts. This is where you will add custom code.

Run Setup Routine

Now that you've added Factor as a dependency. Run Factor from the command line and it should run the setup routine.

npx factor dev

Note: Factor's setup routine only runs if there is no factor property in your package.json.


Once you've run setup, yourpackage.json will look something like this:

  "name": "my-app",
  "factor": {
    "load": {
      "app": "index",
      "server": "index"
    "app": {
      "name": "Example",
      "url": "",
      "description": "My app",
      "email": "Example <[email protected]>"
    "admins": ["[email protected]"]
  "dependencies": {
    "@factor/core": "^1.0.0"

Add A Theme

Now you'll have a blank app that is ready for some custom code. If you want a head start, then that's what themes are for.

To add a theme, just add it as a dependency:

npm add @factor/theme-alpha

Other Files

Environmental Variables with .env

Your .env (dotenv) file is where you'll store all your secret API keys, at least locally. Create this file:

# Authentication Decode/Encode Secret

You'll need to add additional keys to this file to enable your "key services" discussed below.

Ignore Files in Git with .gitignore

Assuming you're using Git to manage your source code, another crucially important file to add to your project is .gitignore. You'll need to make sure you don't commit a few Factor/Node files to source:

# factor

# node

# secrets (Important!)