Skip to main content

Future flags

Similarly to how React Router approaches breaking changes, the @shopify/shopify-app-react-router package also uses future flags.

Bigger features and breaking changes are initially added behind a future flag. This means that they're disabled by default, and must be manually enabled by setting the appropriate flag in the future option of the shopifyApp function.

This allows apps to gradually adopt new features, and prepare for breaking changes and major releases ahead of time.

Anchor to configurationSetting future flags

To opt in to a feature, simply enable the appropriate flag in the future option of the shopifyApp function.

Once a flag is set, the returned shopify object will start using the new APIs, including using any new types. That allows apps to rely on TypeScript to use a feature regardless of a flag being enabled or not.

Enable future flags

/app/shopify.server.ts

import {shopifyApp} from '@shopify/shopify-app-react-router/server';

export const shopify = shopifyApp({
// ...
future: {
unstable_newFeature: true,
},
});

Anchor to unstable-apisUnstable APIs

When introducing new features to the package for which we want to gather feedback, we will add them behind a future flag, starting with the unstable_ prefix.

That allows early adopters to try them out individually, without having to install a release candidate package.

When the feature is ready for release, the future flag will be removed and it will be available by default.

In this example, shopify has a new function called newFeature. If the future flag is disabled, TypeScript will be unaware of the new function, and the app will fail to compile if it tries to use it.

Use unstable APIs

/app/routes/*.tsx

import type {LoaderFunctionArgs} from 'react-router';

import {shopify} from '~/shopify.server';

export const loader = async ({request}: LoaderFunctionArgs) => {
const result = shopify.newFeature(params);

return null;
};

Anchor to breaking-changesBreaking changes

Similarly to unstable APIs, breaking changes will be introduced behind a future flag.

This allows apps to prepare for the next major version ahead of time, and to gradually adopt the new APIs.

When the next major version is released, the future flag will be removed, and the old code it changes will be removed. Apps that adopted the flag before then will continue to work the same way with no new changes.

Anchor to flagsSupported flags

There are currently no future flags in the current version.