gatsby-attainlabs-cms

A Gatsby plugin that downloads and syncs index.tsx components from the Attain Labs CMS hosted in Azure Repos into your Gatsby project at build time.

This is especially useful for keeping brand-specific and global CMS blocks up to date across Gatsby projects without manual copying.

Installation

npm install gatsby-attainlabs-cms

Setup

1. Add environment variable

At the root of your Gatsby site, create a .env file if it doesn’t already exist:

touch .env

Inside the file, add your Azure DevOps Personal Access Token (PAT):

PERSONAL_ACCESS_TOKEN=xxxxxxxxxxxxxxxx

⚠️ Do not prefix this with GATSBY_.
That prefix exposes variables to the browser bundle, which is not safe for secrets.

2. Load .env in Gatsby

At the top of your gatsby-config.js, load dotenv:

require("dotenv").config({
  path: `.env.${process.env.NODE_ENV}`,
});

3. Configure the plugin in gatsby-config.js

module.exports = {
  plugins: [
    {
      resolve: "gatsby-attainlabs-cms",
      options: {
        brand: "Cash Money", // LendDirect | Cash Money | Heights Finance | Attain Finance
        // personalAccessToken: "optional-fallback", // not recommended, but supported
        environment: "production", // production | staging | dev
        // azureBranch: "my-feature-branch", // Optional: Override branch for non-production environments
        fetch: ["blogs", "disclaimers", "faqs"], // Array of data to fetch from database
        debug: false, // Console logs blocks created
      },
    },
  ],
};

Environment Options

• production: Forces content sync from the master branch.
• staging: Automatically fetches content from the latest active Pull Request branch in Azure DevOps. Falls back to master if no PR is active.
• dev: Skips component sync and data fetching. Useful for local development speed.
• Default behavior: If environment is unspecified or other values, it defaults to the azureBranch option or master.

---

## Behavior

- Downloads brand-specific components into:
  - `src/cms/components/brand/`
  - `src/cms/components/global/`
  - `src/cms/gatsby-plugin-theme-ui/`

- Requires an Azure DevOps Personal Access Token (PAT) to authenticate requests.

- If the PAT is missing, the plugin will **warn and skip execution** instead of failing the build.

- If the `brand` option is missing or invalid, the plugin will **throw an error** and stop the build.
  Valid values are:
  - `LendDirect`
  - `Cash Money`
  - `Heights Finance`
  - `Attain Finance`

---

## Global Data Context Hook

The plugin automatically provides a **Global Data Context** containing:
- `blogs` (All blog posts for the brand)
- `trustpilotReviews` (Trustpilot business data + recent 5-star reviews)
- `disclaimers` (Brand-specific disclaimers)
- `faqs` (Brand-specific FAQs)

This data is injected into the context of every page created by the plugin and is accessible in any React component via the `useCmsData` hook.

### Usage

Import `useCmsData` directly from the package:

```tsx
import { useCmsData } from "gatsby-attainlabs-cms";

const MyComponent = () => {
  const { blogs, trustpilotReviews, disclaimers, faqs } = useCmsData();

  return (
    <div>
      {/* Example: Display Trustpilot star rating */}
      {trustpilotReviews && (
          <div>{trustpilotReviews.businessData.stars} Stars</div>
      )}

       {/* Example: List Disclaimers */}
      {disclaimers?.map((d) => (
        <div key={d.id} dangerouslySetInnerHTML={{ __html: d.content }} />
      ))}
    </div>
  );
};

Troubleshooting

PAT missing warning

If you see:

⚠️ [gatsby-attainlabs-cms] No PERSONAL_ACCESS_TOKEN found...

➡️ Double-check that .env exists and is loaded in gatsby-config.js.

Invalid brand option

If you see:

[gatsby-attainlabs-cms] Invalid or missing "brand" option.
You must specify one of: LendDirect, Cash Money, Heights Finance

➡️ Make sure you pass a valid brand in gatsby-config.js.

Token in client code

Don’t use GATSBY_PERSONAL_ACCESS_TOKEN. That will leak your secret into the browser bundle. Always use PERSONAL_ACCESS_TOKEN.