Flatfile Space Configuration Plugin
Programmatically set up and configure a new Flatfile Space with workbooks, sheets, documents, and metadata from a single configuration object.
The @flatfile/plugin-space-configure
plugin is designed to programmatically set up and configure a new Flatfile Space. It operates within a server-side listener, typically responding to the ‘space:configure’ event which is triggered when a new Space is created.
Its primary purpose is to define the entire structure of a Space from a single configuration object. This includes creating one or more Workbooks, defining their Sheets with specific fields and actions, setting Space-level properties like metadata and themes, and adding initial documents such as a welcome guide.
The plugin also includes a secondary utility, dataChecklistPlugin
, which can automatically generate and maintain a “Data Checklist” document within the Space. This document provides a summary of all the fields and data types defined in the Space’s workbooks, serving as a handy reference for users.
This plugin is essential for developers who want to create templatized, repeatable, or dynamically generated Space configurations for their users.
Installation
Install the plugin using npm:
Configuration & Parameters
The configureSpace
function takes a setup
object as its primary configuration. This can be a static object or a function that returns an object.
The setup
object has the following properties:
workbooks
- Type:
Partial<Flatfile.CreateWorkbookConfig>[]
- Required: Yes
- Description: An array of workbook configuration objects. Each object defines a workbook to be created in the Space. You can specify its name, sheets, actions, labels, etc. This is the core of the Space’s data structure.
- Default: There is no default; you must provide at least an empty array
[]
.
space
- Type:
Partial<Flatfile.SpaceConfig>
- Required: No
- Description: An object to configure the Space itself. You can set metadata (like themes), the primary workbook ID (though the plugin handles this automatically), and other space-level settings.
- Default: The plugin will automatically set the
primaryWorkbookId
to the ID of the first workbook created. Other properties are unset by default.
documents
- Type:
Flatfile.DocumentConfig[]
- Required: No
- Description: An array of document configuration objects. Each object creates a document in the Space’s sidebar. This is useful for providing welcome text, instructions, or guides.
- Default: No documents are created by default.
config
- Type:
object
- Required: No
- Description: An object for plugin-specific configurations.
maintainWorkbookOrder
(boolean): If set totrue
, the plugin will configure the Space’s sidebar to display the workbooks in the same order they are defined in theworkbooks
array.
- Default:
{ maintainWorkbookOrder: false }
Usage Examples
Basic Usage
Configuration with Workbook and Sheets
Advanced Usage with Callback
Using Data Checklist Plugin
Error Handling Example
API Reference
configureSpace(setupFactory, callback)
Creates a Flatfile listener plugin that listens for the job:ready
event with the topic space:configure
. When triggered, it configures the Space according to the provided setup. It handles creating workbooks, updating the space with a primary workbook, and creating documents.
Parameters:
-
setupFactory
:Setup | (event: FlatfileEvent) => Setup | Promise<Setup>
- The configuration for the space. This can be a static object or an async function that receives the event context and returns a configuration object.
-
callback
:(event: FlatfileEvent, workbookIds: string[], tick: TickFunction) => any | Promise<any>
(Optional)- An optional async function that is executed after the space and workbooks have been successfully configured. The job progress will be at 50% when the callback is invoked.
event
: The original FlatfileEvent that triggered the job.workbookIds
: An array of strings containing the IDs of the workbooks that were created.tick
: A function to update the job’s progress percentage and message.
Returns: (listener: FlatfileListener) => void
dataChecklistPlugin()
A utility plugin that creates and maintains a “Data Checklist” document in a Space. It listens for workbook:created
and workbook:updated
events, then inspects all workbooks and sheets to generate an HTML document summarizing the data model.
Parameters: None
Returns: (listener: FlatfileListener) => void
Troubleshooting
If a Space fails to configure, check the “Jobs” log in the Flatfile Dashboard for the specific Space. The space:configure
job will show an error message detailing what went wrong.
Common issues include:
- Malformed configuration objects (e.g., incorrect field types in a sheet definition)
- API permission errors - ensure your agent has the necessary permissions to create workbooks, documents, and update spaces
Notes
Special Considerations
- This plugin is designed to be used in a server-side listener environment
- The
configureSpace
plugin is specifically tied to thespace:configure
job topic. It will not run on other events - The
dataChecklistPlugin
listens forworkbook:created
andworkbook:updated
events. It will automatically update its document if you add or change workbooks in the Space after the initial configuration
Error Handling Patterns
- The plugin is built on top of
@flatfile/plugin-job-handler
, which provides robust job management. If any of the API calls made by the plugin fail, the job handler will catch the error, mark the job as ‘failed’, and provide the error message in the Flatfile UI - For custom logic inside the optional
callback
function, you are responsible for your own error handling. It is best practice to usetry/catch
blocks. If you rethrow an error from the callback, the job will be marked as ‘failed’
Default Behavior
- The plugin will automatically set the
primaryWorkbookId
to the ID of the first workbook created - Workbooks are displayed in the sidebar in the order they are created unless
maintainWorkbookOrder
is set totrue
- No documents are created by default unless specified in the configuration