Notice something different? Get the story behind our exciting new brand
Contentstack
search
Changelog

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

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

PropertyTypeDescriptionDefault Value
baseDirStringDirectory path where content files are stored locally./contents 
localeStringDefault locale for content queries'en-us' 
referenceDepthNumberNested 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"