Extending the project schema

To add your own fields so that your team can easily update certain project settings in the studio, a developer needs to edit the project schema.

To do this, you'll need to open the Project schema for your project and add in the fields that you'd like. Follow the steps below to do this.

Adding fields to the project schema

We'll set up our project for basic auth and SEO in this example.

Open the Developer area, then click Schemas

Click Project schema and the right-hand drawer will open

Click the Edit schema button, this will open the schema editor

Add what you'd like to be editable in your schema

In this example, we're adding a title prefix and suffix and adding HTTP basic authentication. You can copy the same schema from below:

{
  "schema": [
    {
      "name": "Page",
      "fields": [
        {
          "label": "Title Prefix",
          "field": "frontasticPageTitlePrefix",
          "type": "string",
          "translatable": true,
          "default": ""
        },
        {
          "label": "Title Suffix",
          "field": "frontasticPageTitleSuffix",
          "type": "string",
          "translatable": true,
          "default": " | Made with Frontastic"
        }
      ]
    },
    {
      "name": "Basic Authentication",
      "fields": [
        {
          "label": "Username",
          "field": "frontasticBasicAuthUsername",
          "type": "string",
          "translatable": false,
          "default": "frontastic"
        },
        {
          "label": "Password (leave empty to disable basic auth)",
          "field": "frontasticBasicAuthPassword",
          "type": "string",
          "translatable": false,
          "default": ""
        },
        {
          "label": "Realm",
          "field": "frontasticBasicAuthRealm",
          "type": "string",
          "translatable": false,
          "default": "Access denied"
        },
        {
          "label": "IP/IP-Range Whitelist",
          "field": "frontasticBasicAuthIpWhitelist",
          "type": "group",
          "min": 0,
          "fields": [
            {
              "label": "IP/IP-Range",
              "field": "ipRange",
              "type": "string",
              "translatable": false
            }
          ]
        },
        {
          "label": "Comment",
          "field": "comment",
          "type": "string",
          "translatable": false
        }
      ]
    }
  ]
}

We're setting our default prefix as empty and the suffix as | Made with Frontastic so when a customer clicks on a page, their tab would say "<page folder name> | Made with Frontastic". For example:

See the schemas article for more information about schemas.

Once you're happy with your changes, click Validate which will check if your JSON is valid and will show any errors you might have

If there are no errors, you can click the Publish button to save your changes

Click the Project icon on the left-hand navigation. You should now have your new fields. They'll also be available to anyone who has access to your project in the studio. See the managing project settings in the studio article for more information.

You can then access the configured values from the code in the context.

The project settings can be changed for each environment separately. So if you'd like the same settings on each environment, you'll need to edit the settings in each environment.

If you want to update your schema, be sure to keep in all the previous fields to ensure Backwards Compatibility.

Feature flags example

You can also use the project schema to add feature flags to your project to test specific features, which can be activated and deactivated by users of the studio. By using the project schema, means that you can enable these features in different environments as well.

Typical usage of feature flags include:

Testing a feature on the staging system with the same code deployed on staging and production
This is very useful when you don't want to rely on code branches, and it's usually the most efficient way to ensure you're able to iterate and deploy quickly. But, a single active code branch is easier from a development process point of view.
Activating and deactivating features easily to test user behavior
So you could give the ability to users in the studio to run tests with real customers, for example, activating a payment service for a particular time.

Below is an example of a schema we could copy and paste into the schema editor with 3 features:

{
  "schema": [
    {
      "name": "Feature flags",
      "fields": [
        {
          "label": "Show related products on the product detail page",
          "field": "showRelatedProducts",
          "type": "boolean",
          "default": false
        },
        {
          "label": "Allow users to create a wishlist and add items to it",
          "field": "enableWishlist",
          "type": "boolean",
          "default": false
        },
        {
          "label": "Allow users to pay using Apple Pay",
          "field": "enableApplePay",
          "type": "boolean",
          "default": false
        }
      ]
    }
  ]
}

The ActionContext, DataSourceContext, and DynamicPageContext all have a property frontasticContext which has a property projectConfiguration which contains the project configuration configured in studio.

You can, for example, access the project configuration inside an action hook:

export const getWishlist: ActionHook = async (
  request: Request,
  actionContext: ActionContext
) => {
  if (
    actionContext.frontasticContext.projectConfiguration.enableWishlist !== true
  ) {
    return {
      statusCode: 200,
      body: JSON.stringify({
        enabled: false,
        wishlist: [],
      }),
    };
  }
  return {
    statusCode: 200,
    body: JSON.stringify({
      enabled: true,
      wishlist: [
        /* … */
      ],
    }),
  };
};

The project configuration isn't automatically exposed to the frontend. So you can't access it in Frontend components. This ensures secret values in the project configuration aren't exposed to customers.

However, if you need individual options from the project configuration in the frontend, you can create a custom action that returns a subset of the project configuration and can be called from the frontend.