---
title: Project Seeding API


---
The Project Seeding API provides a simple way to programmatically seed projects. A common use case might be to set up an example project.

## Configuration

Example: `seeding.js`

```js
{
  users: [
    {
      _importHandle: ':admin',
      firstName: 'John',
      lastName: 'Doe',
      email: 'john@livingdocs.io',
      admin: true, // default false
      password: 'Secret-Phrase'
    },
    {
      _importHandle: ':editor',
      firstName: 'Clark',
      lastName: 'Kent',
      email: 'john+editor@livingdocs.io',
      password: 'Secret-Phrase'
    }
  ],

  projects: [
    // project with embedded design
    {
      __recreateIfItExists: false,
      __update: true,

      handle: 'my-embedded-design-project',
      owner: ':admin',
      groups: [
        {
          label: 'Editors',
          policies: [
            {effect: 'ALLOW', action: 'document.create', contentType: '*'},
            {effect: 'ALLOW', action: 'document.read', contentType: '*'},
            {effect: 'ALLOW', action: 'document.update', contentType: '*'},
            {effect: 'ALLOW', action: 'document.publish', contentType: '*'},
            {effect: 'ALLOW', action: 'document.delete', contentType: '*'},
          ]
        },
        {
          label: 'Readers',
          policies: [
            {effect: 'ALLOW',  action: 'document.read', contentType: 'regular'}
          ]
        }
      ],
      groupMemberships: {
        'Editors': [':admin'],
        'Readers': [':editor']
      },
      config: require('./projects/service'), // the project config
      secrets: [{name: 'my-secret', value: 'super-secret'}]
    },
    // project with reference design
    // Deprecated in: [`release-2026-01`](/operations/releases/release-2026-01/)
    {
      __recreateIfItExists: false,
      __update: true,
      handle: 'my-referenced-design-project',
      owner: ':admin',
      groups: [],
      groupMemberships: {},
      channel: {
        designName: 'some-design',
        designVersion: ':some-version'
      },
      config: require('./projects/website') // the project config
    }
  ]
}
```

### Users

You can define users in two places:

- In the seeding configuration under `users`(like in the example above)
- In the `conf/secrets/local.js` file under `development.users`. This way you can define your own email and password

### Projects

Project configurations can be of three types:

- Embedded design
- Referenced design Deprecated in: [`release-2026-01`](/operations/releases/release-2026-01/)
- Multi-channel Configuration (where only referenced designs can be used) Removed in: [`release-2025-07`](/operations/releases/release-2025-07/)

#### Groups

- [Available scopes for groups](/guides/authentication/access-rights/llms.txt)
- Available policy effects: `ALLOW`, `DENY`
- Available policy actions: `document.metadata.update`, `metadata.update`, `document.create`, `document.read`, `document.update`, `document.delete`, `document.publish`, `dashboard.get`

#### Group Memberships

- The keys of `groupMemberships` are the `group` labels,
- The values of `groupMemberships` are arrays with user `_importHandle`'s

#### Config

[Project Config](/reference/project-config/llms.txt)

#### Secrets

Secret values for usage inside a project. Example usage may be for API secrets of external services.

## Usage

You can register an initialized hook.

Example:

```js
// Setup Default Projects
liServer.registerInitializedHook(async function initSeeding() {
  const tasksApi = liServer.features.api('li-tasks')

  const defaultSeedingConfig = require('./seeding')
  try {
    // if 'useDevUsers' is true the users will be taken from the local.js file.
    // 'file' is used only for logging purposes.
    await tasksApi.setupProjects(defaultSeedingConfig, {
      useDevUsers: false,
      file: './example/seeding.js'
    })
  } catch (err) {
    // continue server setup in case of an error
    liServer.log.error(err)
  }
})
```