Private betav0.1.0
Docs
Format developer documentation

Installation

How to install Format Studio

Standalone install

Useful

If you already have a framework in place, you may want to also read our framework-specific pages. For example: Next.js.

Create your project

If you're coming to Format without an existing codebase to install into, or just want to test the workflow for the first time, we'd recommend a standalone install. You will be prompted with a few questions and end up with a codebase that's ready to start developing Format documents.

If you want to install Format into an existing codebase or repo, you can follow the existing codebase guide instead.

npm create format@latest
pnpm create format@latest
yarn create format@latest
bun create format@latest

Run your project

After the setup is complete, you can run your project.

npm run dev
pnpm run dev
yarn dev
bun run dev

You will be prompted to sign in to Format or create an account. Format Studio will then be launched on: http://localhost:1234.

http://localhost:1234/welcome
Format Studio running in the browser

Existing codebase

To add Format to an existing codebase or repo, you can use npx format init to automate the setup. This will add your Format config, the npm scripts, the gitignore entries, and the packages. Each step will confirm before editing anything.

# Install the Format CLI
npm install "@format.dev/cli" --save-dev

# Inside your repo directory, run the Format project init script
npx format init
# Install the Format CLI
pnpm add "@format.dev/cli" --save-dev

# Inside your repo directory, run the Format project init script
pnpm dlx format init
# Install the Format CLI
yarn add "@format.dev/cli" --dev

# Inside your repo directory, run the Format project init script
yarn dlx format init
# Install the Format CLI
bun add "@format.dev/cli" --dev

# Inside your repo directory, run the Format project init script
bun x format init

Manual installation

Prefer nothing touching your files? The full setup by hand:

Install the Format CLI

You can read the docs to understand more about the Format CLI.

npm install "@format.dev/cli" --save-dev
pnpm add "@format.dev/cli" --save-dev
yarn add "@format.dev/cli" --dev
bun add "@format.dev/cli" --dev

Add the required files and directories

Recreate the following directory structure.

documents
format.config.json
package.json
tsconfig.json

Add format dev to your package.json scripts

package.json
{
	"scripts": {
		"dev": "format dev"
	}
}

Add the configuration file

This should be placed in the root, at the same level as the package.json.

format.config.jsonc
{
	"$schema": "https://format.dev/schema/format-config.json",
	"version": "0.1.2",
	"framework": "react"
}

You can read more about the available options in the configuration section.

Add the Format packages

The packages you add will differ slightly based on the framework you are using.

npx format add "@format.dev/react" "@format.dev/client"
pnpm dlx format add "@format.dev/react" "@format.dev/client"
yarn dlx format add "@format.dev/react" "@format.dev/client"
bun x format add "@format.dev/react" "@format.dev/client"
npx format add "@format.dev/vue" "@format.dev/client"
pnpm dlx format add "@format.dev/vue" "@format.dev/client"
yarn dlx format add "@format.dev/vue" "@format.dev/client"
bun x format add "@format.dev/vue" "@format.dev/client"
npx format add "@format.dev/client"
pnpm dlx format add "@format.dev/client"
yarn dlx format add "@format.dev/client"
bun x format add "@format.dev/client"

Update your gitignore

Add _generated (or your required --out-dir) to your .gitignore.

.gitignore
# Format build
_generated
tsconfig.json
{
	"extends": "@format.dev/cli/tsconfig.recommended",
	"compilerOptions": {
		"jsx": "react-jsx"
	}
}
tsconfig.json
{
	"extends": "@format.dev/cli/tsconfig.recommended",
	"compilerOptions": {
		"jsx": "preserve",
		"jsxImportSource": "vue"
	}
}
tsconfig.json
{
	"extends": "@format.dev/cli/tsconfig.recommended"
}

Run the project

After the setup is complete, you can run your project.

npm run dev
pnpm run dev
yarn dev
bun run dev

You will be prompted to sign in to Format or create an account. Format Studio will then be launched on: http://localhost:1234.

Was this page helpful?