Configuration

Use a Format studio config file to control the core behavior of Studio.

Name your config file format.config.json and place it in the root of your repo or package, next to the package.json. You can also use the .jsonc extension.

The $schema field gives you autocomplete and validation in your editor.

format.config.json

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

Reference

Name	Description
`version`Required	The Format release version this project is pinned to. Every installed Format package is kept in lockstep with this version. Set it to the version you want and run `format update` to apply it everywhere. Must be an exact version, never a range.
`framework`Required	Which framework to use for your Format documents.
`$schema`	Path or URL to the JSON schema for this file, used by editors for autocomplete and validation. Set it to: https://format.dev/schema/format-config.json.
`rootDir`	The root directory where all Format code is located, relative to the config file. Change this if you want to root your Format documents and data under a different directory. For example, setting this to "format" would result in your documents being located in "format/documents".
`sharedAssetsDir`	The directory for assets shared across documents, as a relative path. Defaults to `assets` under the root dir, mirroring each document's own `./assets/` folder. In your template code, this resolves as `"./"`: place `image.png` in this directory and reference it as `"./image.png"`. Somewhat equivalent to a `public` dir in a Vite project.
`cwd`	Override the base path resolution for Format. Useful if you want to have your config in a different directory to the root of your project. For example, if you put your `format.config.json` file in a `config` directory, you could set `cwd` to `../` to tell Format to look for your project in the parent directory.
`dotEnvPath`	Specify a path to a `.env` file. If path is relative, this is resolved relative to `cwd`.
`pandaCss`	Panda CSS configuration options. The `PandaCssPostCssPluginOptions` type is exposed as `PluginOptions` from the `@pandacss/dev/postcss` package. Useful resource: https://github.com/chakra-ui/panda/blob/main/packages/postcss/src/index.ts

Details

`version`

Required

Description

The Format release version this project is pinned to. Every installed Format package is kept in lockstep with this version. Set it to the version you want and run format update to apply it everywhere. Must be an exact version, never a range.

Type

string

Example

"0.1.2"

`framework`

Required

Description

Which framework to use for your Format documents.

Type

"react" | "vue" | "html"

`$schema`

Description

Path or URL to the JSON schema for this file, used by editors for autocomplete and validation. Set it to: https://format.dev/schema/format-config.json.

Type

string

Example

"https://format.dev/schema/format-config.json"

`rootDir`

Description

The root directory where all Format code is located, relative to the config file. Change this if you want to root your Format documents and data under a different directory. For example, setting this to "format" would result in your documents being located in "format/documents".

Type

string

Default value

"./"

Example

"format"

`sharedAssetsDir`

Description

The directory for assets shared across documents, as a relative path. Defaults to assets under the root dir, mirroring each document's own ./assets/ folder. In your template code, this resolves as "./": place image.png in this directory and reference it as "./image.png". Somewhat equivalent to a public dir in a Vite project.

Type

string

Default value

"assets"

Example

"./shared-assets"

`cwd`

Description

Override the base path resolution for Format. Useful if you want to have your config in a different directory to the root of your project. For example, if you put your format.config.json file in a config directory, you could set cwd to ../ to tell Format to look for your project in the parent directory.

Type

string

Default value

process.cwd()

Example

"../"

`dotEnvPath`

Description

Specify a path to a .env file. If path is relative, this is resolved relative to cwd.

Type

string

Default value

resolve(cwd, .env)

Example

"../../.env"

`pandaCss`

Description

Panda CSS configuration options. The PandaCssPostCssPluginOptions type is exposed as PluginOptions from the @pandacss/dev/postcss package. Useful resource: https://github.com/chakra-ui/panda/blob/main/packages/postcss/src/index.ts

Type

{ enabled: boolean, postCssConfig: PandaCssPostCssPluginOptions }

Default value

{
	enabled: false,
	postCssConfig: {
		cwd: rootDir || "./",
		configPath: resolve(rootDir || "./", "panda.config.ts")
 }
}

Was this page helpful?