Get Started with DataSync Filesystem SDK
The Contentstack DataSync Filesystem SDK enables developers to efficiently synchronize and query Contentstack data directly from a local file system, optimizing content delivery and access.
Prerequisites
- Node.js version 20 or higher
- Data synchronized through Contentstack DataSync
Installation and Setup
To use the DataSync Filesystem SDK, integrate it into the DataSync Boilerplate to query content synchronized to the local filesystem.
Run the following command to install the SDK:
npm install contentstack/datasync-filesystem-sdk
Initializing the SDK
Initialize the SDK using the configuration provided in the datasync-boilerplate repository or by using the sample configuration shown below.
import { Contentstack } from 'datasync-filesystem-sdk'
const Stack = Contentstack.Stack(config)
Configuration Properties
| Property | Type | Description | Default Value |
|---|---|---|---|
| baseDir | String | Directory path where content files are stored locally | ./contents |
| locale | String | Default locale for content queries | 'en-us' |
| referenceDepth | Number | Nested reference depth for .includeReferences() | 2 |
Configuration Overview
Here's an overview of the SDK's configurable properties for databases and collections.
{
contentStore: {
baseDir: './_contents',
defaultSortingField: 'updated_at',
locale: 'en-us',
projections: {
_content_type_uid: 0,
},
referenceDepth: 2,
},
}
Basic Queries
Once you have initialized the SDK, you can start querying the filesystem SDK. This section provides an overview of basic queries.
Sample SDK Query
import { Contentstack } from 'datasync-filesystem-sdk'
const Stack = Contentstack.Stack(config)
Stack.connect()
.then(() => {
return Stack.contentType('blog')
.entries()
.language('en-gb') // Optional. If not provided, defaults to en-us
.include(['authors'])
.includeCount()
.includeContentType()
.queryReferences({'authors.firstName': 'R.R. Martin'})
.then((result) => {
// Your result would be
// {
// entries: [...], // All entries, whose first name is R.R. Martin
// content_type_uid: 'blog',
// locale: 'en-gb',
// content_type: {...}, // Blog content type's schema
// count: 3, // Total count of blog content type
// }
})
})
.catch((error) => {
// handle errors..
})
Note: Call .connect() to initiate SDK queries.
Query a Single Entry
This query returns the first entry that matches query filters in the result
Stack.contentType('blog')
.entry() // OR .asset()
.find()
.then((result) => {
// Response
// result = {
// entry: any | null,
// content_type_uid: string,
// locale: string,
// }
})
.catch(reject)
Querying a set of entries, assets or content types
This query returns the entry/ assets/ content types that match the query filters in the results
Stack.contentType('blog')
.entries() // for .assets()
.includeCount()
.find()
.then((result) => {
// Response
// result = {
// entry: any | null,
// content_type_uid: string,
// count: number,
// locale: string,
// }
})
.catch(reject)
Limitations
- Responses always include content_type_uid and locale keys.
- If .language() is not specified, the first language defined in config.defaultLocale is used.
- Single-entry queries (using .entry() OR .findOne()) return { entry: {} }, if found, or { entry: null }, if not found.
- Multiple-entry queries return { entries: [ {...} ] }.
- Referenced assets are included by default; use.excludeReferences()to exclude references (including assets) from responses.
More Resources
DataSync FileSystem SDK API Reference
More articles in "Use DataSync"
