{frontMatter.description}
## Prerequisites Before diving into the code, ensure you have the following prerequisites in place: - A Front-Commerce project configured and ready to use - Basic knowledge of [Remix routes](./your-first-route.mdx) - [FAQ GraphQL Module](https://gitlab.blackswift.cloud/front-commerce/front-commerce/-/tree/main/skeleton/example-extensions/faq-demo/graphql) installed and configured if you want to execute code samples without any changes ## Loading Data In your app directory, create a new route file (e.g., `app/routes/_main.faq.$slug.tsx`) and add the following code: ```tsx title="app/routes/_main.faq.$slug.tsx" import { json } from "@front-commerce/remix/node"; import { useLoaderData } from "@front-commerce/remix/react"; import type { LoaderFunctionArgs } from "@remix-run/node"; import FaqDetail from "theme/pages/FaqDetail"; import { isRouteErrorResponse, useRouteError } from "@remix-run/react"; import { FaqEntryQueryDocument } from "~/graphql/graphql"; import { FrontCommerceApp } from "@front-commerce/remix"; // The route exports a `loader` function that is responsible // for fetching data and throwing errors, ensuring that // the main component is only rendered in the "happy path". export const loader = async ({ context, params }: LoaderFunctionArgs) => { const { slug } = params; // The `loader` uses the `FrontCommerceApp` class to access the Front-Commerce // core from Remix. In this example, we use it to fetch data from the GraphQL // unified API (similar to the one you're used to). const app = new FrontCommerceApp(context.frontCommerce); const response = await app.graphql.query(FaqEntryQueryDocument, { input: { slug }, }); if (!response.faqEntry) { throw new Response("Question not found", { status: 404 }); } return json({ faqEntry: response.faqEntry, }); }; // The main component is a plain React component that receives // the data from the loader, using Remix fetching primitives (`useLoaderData`) // both on the server and on the client. export default function Component() { const { faqEntry } = useLoaderDataFAQ : question not found
;
}
};
```
This is an example of a route that fetches a question from the GraphQL API and
renders it using a `{frontMatter.description}
# File-based routing Front-Commerce uses Remix. Remix uses [API Routes](https://remix.run/docs/en/main/guides/api-routes) to handle all the routing of you application, and display the correct page when a user navigates to a URL. All routes are located under `app/routes` folder. API Routes will use the default export of each Route file to generate the route's UI. Go ahead and create a new route `hello-world.tsx`, that will display content when users browse http://localhost:4000/hello-world: ```tsx title="app/routes/hello-world.tsx" export default function HelloWorld() { return (Hello world!
Hello {name}!
Hello {name}!
Contact us:
Oops, something bad happened !
);
}
```
# External resources
- [Contact page example](https://remix.run/docs/en/main/start/tutorial#the-contact-route-ui)
- [API Routes documentation](https://remix.run/docs/en/main/guides/api-routes).
- [Loading data from an external API](https://daily-dev-tips.com/posts/remix-loading-data-from-an-external-api/)
- [Interactive Remix routing](https://interactive-remix-routing-v2.netlify.app/)
---
# Your first test 🧪
URL: https://developers.front-commerce.com/docs/3.x/get-started/your-first-test
{error.toString()}
{frontMatter.description}
{frontMatter.description}
This method can also be useful if you are planning to set up a Store Locator in your shop. If you are willing to display these pickups in the checkout this guide will help you. However if you are willing to save the needed information in the user's quote, please have a look at [Use custom shipping information](./use-custom-shipping-information) instead. :::info Prerequisite To go through this guide, you'll need to have a created a [new extension with a GraphQL module](./extend-the-graphql-schema) and to know how to [fetch data in a component](./create-a-business-component#fetching-our-data). ::: ## Add pickups to your GraphQL Schema The goal here is to be able to fetch a list of pickups from GraphQL. You could create your own types and your custom implementation. However, in Front-Commerce, we've created a GraphQL interface named `FcPickup` that ensures that any pickup point can be displayed in the PostalAddressSelector component of Front-Commerce.Loading...
;
}
if (error) {
return Error...
;
}
return (
{frontMatter.description}
## Set an attribute as sortable{frontMatter.description}
import Figure from "@site/src/components/Figure"; The concept lying behind a Design System is to document how your brand communicates with its users. This goes from global guides such as "Voice and tone", "Code Convention", "Accessibility"… to components documentation that focus on where and how to use a specific component. Such a Design System should be customized to the way your team(s) work and should evolve according to your needs. But with Front-Commerce, we provide you a base you can iterate on. Technically, we use [Storybook](https://storybook.js.org/) which is a tool that references `stories` for each component you want to document. With these stories, it will launch for you a website that allows you to browse through your components. In this guide we will go through a basic tutorial that gets you started with writing stories within Front-Commerce. But if you want to learn more about Storybook, please refer to [its documentation](https://storybook.js.org/basics/writing-stories/). {/* TODO For more detailed information about Front-Commerce specific configurations of Storybook, please refer to TODO */} ## Add your own story In order to add your own story, you need to create a new file, that will document how to use a component and will reference each edge case for this component. Each case will be what we call a `story`. As explained in [Storybook's documentation](https://storybook.js.org/basics/writing-stories/): > A story captures the rendered state of a UI component. To do this, you will create a `.stories.tsx` file next to your component. In this example, we will use the same component as in Create a UI Component: `IllustratedContent.tsx`. Hence, your stories file will be `IllustratedContent.stories.tsx` and will look like this: {/* TODO update : [Create a UI Component](./create-a-ui-component) */} ```tsx title="app/theme/components/molecules/IllustratedContent/IllustratedContent.stories.tsx" import type { Meta, StoryObj } from "@storybook/react"; import IllustratedContent from "./IllustratedContent"; import Icon from "theme/components/atoms/Icon"; import { H3 } from "theme/components/atoms/Typography/Heading"; const meta: MetaShipping within 48h
), }; ``` Thanks to this file, when you launch Storybook (`pnpm run styleguide`), it will **register** the stories for the component `IllustratedContent`. It will make it accessible in the Storybook's website under `app` > `theme` > `components` > `molecules` \> `IllustratedContent`. And if you click on the `Default` story in the navigation, it will display a default story which will show the standard usecase of the `IllustratedContent` component.Shipping within 48h
), }; // highlight-start export const WithContent: Story = { name: "With a lot of content", render: () => (Shipping within 48h
Shipping within 48h
), }; // highlight-end ```{frontMatter.description}
Front-Commerce uses [`analytics`](https://getanalytics.io/) under the hood. If we represent how it works, it would look like this:My component
;
};
```
:::note
Please refer to the
[useTrackOnMount](../../04-api-reference/front-commerce-remix/react.mdx#usetrackonmount)
documentation.
:::
## `useTrackPage`
In tracking scripts, there is often a distinction between the `page` and the
`event` even though a `page` event is only a subset of the `events`. To make
this distinction clear, we provide an enhancer in the same spirit of
`useTrackOnMount` hook but for page events: `useTrackPage`.
Example:
```tsx
import { useTrackPage } from "@front-commerce/remix/react";
function AcmePage() {
useTrackPage("Acme Page");
return Acme Page
;
}
```
:::note
Please refer to the
[useTrackPage](../../04-api-reference/front-commerce-remix/react.mdx#usetrackpage)
documentation.
:::
---
# Custom Plugins
URL: https://developers.front-commerce.com/docs/3.x/guides/analytics/custom-plugins
import AnalyticsFigure from "./assets/analytics.svg";
import Figure from "@site/src/components/Figure";
import ContactLink from "@site/src/components/ContactLink";
import { useState } from "react";
import SinceVersion from "@site/src/components/SinceVersion";
{frontMatter.description}
Plugins are a powerful abstraction that let you: - add a new analytics provider (like Google analytics or Meta pixel) - hook into an existing analytics provider plugin - or add any kind of logic to react to visitor actions Plugins can be broken down into 2 types: - **Provider plugins** - connecting to third party analytic services - **Custom plugins** - additional features, data manipulation, & any other side effects. Both have the same signature, and are registered in the same way, here we will explore how they are implemented within a Front-Commerce app. :::info You can look at the analytics library documentation to learn more about the plugin types. - [Plugins](https://getanalytics.io/plugins) - [Writing Plugins](https://getanalytics.io/plugins/writing-plugins/) :::{frontMatter.description}
## Prerequisites Before configuring Addingwell in Front-Commerce, ensure that you have: - created an [AddingWell account](https://www.addingwell.com/) - setup your own server, as documented in the [Addingwell Get Started](https://docs.addingwell.com/b/2CA8BCF1-E67D-46DF-A2BE-F93017D8FD7A/Getting-started-with-Addingwell) official guide ## With GTM This guide will show you how to integrate Addingwell with Google Tag Manager. This way, the Analytics tag will be implemented with Google Tag Manager but the traffic will head to your custom server. ### Setup GTM You must follow the [Addingwell Send data documentation (Option 1)](https://docs.addingwell.com/b/C45DD221-2773-4DE0-B588-39B60785291A/Send-the-data-to-your-tagging-server). ### Setup GTM Analytics plugin in Front-Commerce Install the Google Tag Manager analytics plugin ```shell pnpm add @analytics/google-tag-manager ``` Then edit your analytics configuration from the `app/config/analytics.ts` to add the Google Tag Manager plugin: ```ts title="app/config/analytics.ts" import { type AnalyticsConfig } from "@front-commerce/core/react"; export default { analytics: { enable: true, debug: process.env.NODE_ENV !== "production", plugins: [ // highlight-start { name: "google-tag-manager", needConsent: false, enabledByDefault: true, settings: (authorization) => { return { containerId: "GTM-XXXXXXXX", // This should be the GTM container ID of the Container that will inject Google Tag not the server container ID }; }, script: () => import("@analytics/google-tag-manager"), }, // highlight-end ], } satisfies AnalyticsConfig, }; ``` ### Setup CSP Then you'll need to update your CSP to allow your Front-Commerce application to communicate with external services. Let's say that your analytics domain is `metrics.my-commerce.net` ```js title="app/config/cspProvider.ts" const appCSPProvider = () => { return { name: "cspConfiguration", values: { contentSecurityPolicy: { __dangerouslyDisable: false, directives: { // highlight-next-line scriptSrc: ["metrics.my-commerce.net", "www.googletagmanager.com"], // We need to add Google Tag Manager to allow GTM to inject GA4 tag into our pages frameSrc: [], styleSrc: [], imgSrc: [], fontSrc: [], // highlight-next-line connectSrc: ["metrics.my-commerce.net"], baseUri: [], }, }, }, }; }; export default appCSPProvider; ``` ## With GA4 ### Setup your server container You first need to follow the Addingwell [gtag.js configuration guide (option 3)](https://docs.addingwell.com/b/C45DD221-2773-4DE0-B588-39B60785291A/Send-the-data-to-your-tagging-server). Please note your custom tagging domain we will need this for the next step (in the guide, we will consider that the domain is `metrics.my-commerce.net`). ### Setup GA4 plugin in Front-Commerce Install the GA4 plugin with the following command: ```shell npm install @analytics/google-analytics ``` Then edit your analytics configuration from the `app/config/analytics.js` to add the Google Tag Manager plugin: ```js title="app/config/analytics.js" export default { analytics: { // highlight-next-line enable: true, debug: process.env.NODE_ENV !== "production", defaultSettings: {}, plugins: [ // highlight-start { name: "google-analytics", needConsent: false, enabledByDefault: true, settings: (authorization) => { return { customScriptSrc: "https://metrics.my-commerce.net/gtag/js?id=G-XXXXXXXX", measurementIds: ["G-XXXXXXXX"], // You can find this measurement ID in your Google Analytics account: Administration > Data Stream gtagConfig: { transport_url: "https://metrics.my-commerce.net", first_party_collection: true, }, }; }, script: () => import("@analytics/google-tag-manager"), }, // highlight-end ], }, }; ``` ### Setup CSP Then you'll need to update your CSP to allow your Front-Commerce application to communicate with you addingwell server. ```js title="app/config/cspProvider.ts" const appCSPProvider = () => { return { name: "cspConfiguration", values: { contentSecurityPolicy: { __dangerouslyDisable: false, directives: { // highlight-next-line scriptSrc: ["metrics.my-commerce.net"], frameSrc: [], styleSrc: [], imgSrc: [], fontSrc: [], // highlight-next-line connectSrc: ["metrics.my-commerce.net"], baseUri: [], }, }, }, }; }; export default appCSPProvider; ``` --- # Examples URL: https://developers.front-commerce.com/docs/3.x/guides/analytics/plugins/examples :::info Feel free to browse [**our examples plugins**](https://github.com/front-commerce/examples), and even contribute to them if you have any ideas! 💡 ::: ## Meta Pixel To track in Meta Pixel, you can use our [example plugin](https://github.com/front-commerce/examples/tree/main/analytics/meta-pixel) as a good starting point. ## Matomo To track in Matomo, you can use our [example plugin](https://github.com/front-commerce/examples/tree/main/analytics/matomo) as a good starting point. --- # Google Analytics 4 URL: https://developers.front-commerce.com/docs/3.x/guides/analytics/plugins/google-analytics-4{frontMatter.description}
## Prerequisites Before configuring Google Analytics 4 in Front-Commerce, ensure that you have: - A GA4 measurement ID. ## Resources - [GA4 Documentation](https://developers.google.com/analytics/devguides/collection/ga4) - [Plugin Documentation](https://getanalytics.io/plugins/google-analytics) ## Installation ```shell pnpm add @analytics/google-analytics ``` ## Configuration ```ts title="app/config/analytics.ts" import { type AnalyticsConfig } from "@front-commerce/core/react"; export default { analytics: { enable: true, debug: process.env.NODE_ENV !== "production", plugins: [ // highlight-start { name: "google-analytics", needConsent: true, settings: (authorization) => { return { measurementIds: ["G-XXXXXXXXXX"], gtagConfig: { anonymize_ip: !authorization, }, }; }, script: () => import("@analytics/google-analytics"), }, // highlight-end ], } satisfies AnalyticsConfig, }; ``` --- # Google Tag Manager URL: https://developers.front-commerce.com/docs/3.x/guides/analytics/plugins/google-tag-manager{frontMatter.description}
## Prerequisites Before configuring Google Tag Manager in Front-Commerce, ensure that you have: - A GTM container ID. ## Resources - [GTM Documentation](https://developers.google.com/tag-manager) - [Plugin Documentation](https://getanalytics.io/plugins/google-tag-manager/) ## Installation ```shell pnpm add @analytics/google-tag-manager ``` ## Configuration ```ts title="app/config/analytics.ts" import { type AnalyticsConfig } from "@front-commerce/core/react"; export default { analytics: { enable: true, debug: process.env.NODE_ENV !== "production", plugins: [ // highlight-start { name: "google-tag-manager", needConsent: true, settings: (authorization, otherAuthorizations) => { // This ensure an event is pushed with current authorizations // right after the plugin's initialization. window.dataLayer = window.dataLayer || []; window.dataLayer.push({ event: "initConsents", userConsents: otherAuthorizations, }); return { containerId: "GTM-XXXXXX", }; }, script: () => import("@analytics/google-tag-manager"), }, // highlight-end ], } satisfies AnalyticsConfig, }; ``` ## Setup CSP You will need to update your CSP to allow your Front-Commerce application to communicate with the GTM servers. ```ts title="app/config/cspProvider.ts" const appCSPProvider = () => { return { name: "cspConfiguration", values: { contentSecurityPolicy: { __dangerouslyDisable: false, directives: { // add-next-line scriptSrc: ["www.googletagmanager.com"], ...[], }, }, }, }; }; export default appCSPProvider; ``` ## User Consent In GTM, you will then be able to leverage several specific things configured in your plugins. First, pushing the `initConsents` event will push the current customer's authorization to your dataLayer as `userConsents` value. You can reference it from a Variable in GTM. Here is an example:{frontMatter.description}
To make sure you're ready, go through this checklist: - [ ] Style your **Offline page**
:::info
This page is accessible when you disable your network while browsing your shop.
If you have `FRONT_COMMERCE_ENV !== "production"`, this page will also be
available at `/__front-commerce/offline`. You can then
[override](./override-a-component.mdx) the
[`theme/pages/Offline`](https://gitlab.blackswift.cloud/front-commerce/front-commerce/-/tree/0cb2bf0bd475e6fcf79d4f4af340636ffcf02821/packages/theme-chocolatine/theme/pages/Offline)
component to make sure that this page suits your brand.
:::
- [ ] Style your **Maintenance page**
:::info
This page is accessible when your backend is in maintenance mode (HTTP 503). If
you have `FRONT_COMMERCE_ENV !== "production"`, this page will also be available
at `/__front-commerce/maintenance`. You can then
[override](./override-a-component.mdx) the
[`theme/pages/Maintenance`](https://gitlab.blackswift.cloud/front-commerce/front-commerce/-/tree/0a9c1d53d22a9cd11d8e4fc9eac016781dfcfa0f/packages/theme-chocolatine/theme/pages/Error/Maintenance)
component to make sure that this page suits your brand.
And take the opportunity to learn more about maintenance mode with
[our guide](./maintenance-mode/01-entering-and-exiting-maintenance-mode.mdx).
:::
- [ ] Ensure your server can serve the application in **HTTPS** mode.
:::info
Front-Commerce is aimed at being exposed in HTTPS when in production mode
(`NODE_ENV === "production"`). It will redirect users to an HTTPS URL if they
try to access a page using HTTP. Cookies are also set with secure mode.
:::
- [ ] Ensure that your PWA is set up.
:::info
It allows users to install your store as a native application on their device.
See the [PWA Setup guide](./pwa-setup.mdx).
:::
- [ ] Override `robots.txt` if necessary.
:::info
By default, your `robots.txt` is generated and looks something like this:
```txt
User-agent: *
Allow: /
(Disallow: / in development)
Sitemap: https://shopURL.com/sitemap.xml
```
You can see how it is generated
[here](https://gitlab.blackswift.cloud/front-commerce/front-commerce/-/blob/5bfd00bfe4c6d7f948418bdc5d018409d5a2d950/packages/remix/seo/robots/index.ts).
If you need to customize your `robots.txt`, override `robots[.txt].tsx` :
```tsx title="app/routes/robots[.txt].tsx"
import type { LoaderFunctionArgs } from "@remix-run/node";
import { generateRobotsTxt } from "@front-commerce/remix/seo";
import { FrontCommerceApp } from "@front-commerce/remix";
const ONE_HOUR = 60 * 60;
const ONE_DAY = 24 * ONE_HOUR;
export function loader({ context }: LoaderFunctionArgs) {
const app = new FrontCommerceApp(context.frontCommerce);
app.services.CacheControl.setCacheable({
sMaxAge: ONE_HOUR,
staleWhileRevalidate: ONE_DAY,
});
return generateRobotsTxt(
[
{
type: "sitemap",
value: new URL("/sitemap.xml", app.config.shop.url).toString(),
},
],
{
allowCrawling: true,
}
);
}
```
:::
---
# Using DataLoaders in GraphQL loaders
URL: https://developers.front-commerce.com/docs/3.x/guides/caching-remote-data/using-dataloaders-in-graphql-loaders
## What are DataLoaders?
DataLoader is a pattern promoted by Facebook, from their internal
implementations, to solve problems with data fetching. We use this name because
it is the name of the reference implementation in Javascript:
[graphql/dataloader](https://github.com/graphql/dataloader).
A DataLoader is instantiated with a **batching function**, which allows data to
be fetched in groups (see
[Batching](../../05-concepts/common-issues-in-the-data-fetching-layer.mdx#batching)).
It also has a caching strategy that prevents fetching the same data twice in the
same request or across requests (see
[Caching](../../05-concepts/common-issues-in-the-data-fetching-layer.mdx#caching)).
:::note
For a better understanding of why we use DataLoaders, read the
[Common issues in the data fetching layer](../../05-concepts/common-issues-in-the-data-fetching-layer.mdx)
guide.
:::
By default every DataLoader provides request-level caching. But this can be
configured to switch to a persistent caching strategy instead (see
[Configure caching strategies](./02-configure-caching-strategies.mdx#caching-strategies)).
We encourage you to read the
[DataLoader readme](https://github.com/graphql/dataloader/blob/main/README.md)
documentation to learn more about how it works.
Front-Commerce provides a factory function to create DataLoaders from your
GraphQL modules while keeping caching strategies configurable. Under the hood,
it is a pure DataLoader instance, so you could use it in a standard manner.
## Using DataLoaders in Front-Commerce
When building a GraphQL module, Front-Commerce will inject a `makeDataLoader`
factory function in your
[module’s `contextEnhancer` function](../../04-api-reference/front-commerce-core/graphql.mdx#contextenhancer-function).
### `makeDataLoader` usage
The `makeDataLoader` factory allows developers to build a DataLoader without
worrying about the current store scope (in a multi-store environment) or caching
concern.
Here is an example based on the use case above:
```ts title="extensions/acme/inventory/graphql/index.ts"
import { createGraphQLModule } from "@front-commerce/core/graphql";
export default createGraphQLModule({
namespace: "AcmeInventory",
loadRuntime: () => import("./runtime"),
typeDefs: /* GraphQL */ `
extend type Product {
qty: Int
}
`,
});
```
```ts title="extensions/acme/inventory/graphql/runtime.ts"
import { createGraphQLRuntime } from "@front-commerce/core/graphql";
import StockLoader from "./loader";
import axios from "axios";
export default createGraphQLRuntime({
contextEnhancer: ({ makeDataLoader, config }) => {
const axiosInstance = axios.create({
baseURL: config.inventoryApiEndpointUrl,
});
return {
// create an instance of the loader, to be made available in resolvers
Stock: new StockLoader(makeDataLoader, axiosInstance),
};
},
resolvers: {
Product: {
qty: ({ sku }, _, { loaders }) => {
// use the loader instance to fetch data
// batching and caching is transparent in the resolver
return loaders.Stock.loadBySku(sku);
},
},
},
});
```
```ts title="extensions/acme/inventory/graphql/loader.ts"
import { reorderForIds } from "@front-commerce/core/graphql";
import type { DataLoaderScopedFactory } from "@front-commerce/core/cache";
import type { AxiosInstance } from "axios";
class StockLoader {
private httpClient: AxiosInstance;
private dataLoader: ReturnType{frontMatter.description}
## How to enable cart caching To enable cart caching, you need to set the environment variable `FRONT_COMMERCE_CART_CACHE_ENABLE` to `true`. Cart will be cached as soon as a call is made to the cart query. :::info Please note that the cart cache functionality is only available for authenticated customers. ::: ## Cache invalidation operations The cart cache has a TTL of 5 minutes, however some mutations will invalidate the cache immediately. Each extension handle invalidation for its native features. ## Automatic cache invalidation using `decorateWithCartCacheExpire` In addition to the automated cache system, you might have manipulate the Cart cache using the `decorateWithCartCacheExpire` function. This function will allow you to decorate a resolver with a function that will invalidate cache. You can see an example of it's usage in the [Gezy Cart Cache Loader](https://gitlab.blackswift.cloud/front-commerce/front-commerce/-/blob/33d409e253ceba26de55160e3bfe03be153447a5/packages/gezy/modules/cart/CachedCartLoader.ts#L31) ## Advanced cache invalidation using `CartCache` loader In addition to the automated cache system, you can also manipulate the Cart cache using the `CartCache` loader. Let's explain this with an example, imagine you want to invalidate the cart cache in a mutation. In your resolver, you can call the `CartCache` loader to invalidate the cache: ```ts title="my-extension/runtime.ts" import { createGraphQLRuntime } from "@front-commerce/core/graphql"; export default createGraphQLRuntime({ resolvers: { Mutation: { myCustomMutation: (_, { cartId }, { loaders }) => { loaders.CartCache.expire(cartId); }, }, }, }); ``` In this example, `myCustomMutation` will invalidate the cart cache for the given `cartId`. You can also use the `CartCache` loader to cache cart with custom query: ```ts title="my-extension/runtime.ts" import { createGraphQLRuntime } from "@front-commerce/core/graphql"; export default createGraphQLRuntime({ resolvers: { Query: { myCustomQuery: (_, { cartId }, { loaders }) => { return loaders.CartCache.cache( cartId, "cart", await loaders.CustomCartLoader.loadById(cartId) ); }, }, }, }); ``` --- # Caching customer data URL: https://developers.front-commerce.com/docs/3.x/guides/caching-remote-data/caching-customer-data{frontMatter.description}
## How to enable customer caching To enable customer caching, you need to set the environment variable `FRONT_COMMERCE_CURRENT_CUSTOMER_CACHE_ENABLE` to `true`. ```title=".env" FRONT_COMMERCE_CURRENT_CUSTOMER_CACHE_ENABLE=true ``` Customer will be cached as soon as a call is made to the customer query. The TTL for the cache is 5 minutes. :::info Please note that the customer cache functionality is only available for authenticated customers. ::: If your Front-Commerce application is configured to use multiple stores, the customer cache is scoped to the current store. EG: - You have a `default` store and a second store named `FR`. - The customer is connected to the `default` store. - Its data will be cached. - The customer switches to the `FR` store, the data cached from the `default` store won't be available for the `FR` store. --- # Change a resolver behavior URL: https://developers.front-commerce.com/docs/3.x/guides/change-resolver-behavior{frontMatter.description}
As an example, we will change the way the Product `meta_description` field value is generated.{frontMatter.description}
## What is a configuration provider? The goal is to give access to a configuration object that contains all the configuration of the store. This configuration object can contain any kind of configuration. It can be flags about a feature activation, some credentials to connect to a remote service, etc. However, not all applications will need every single configuration. For instance, a shop that chose to use [Algolia](https://www.algolia.com/) won't have the same configurations than a shop that chose [Elasticsearch](https://www.elastic.co/) for product search. The goal of the configuration providers is to define the configurations needed for the specific modules you use in your application. On server start, the configuration providers will then be combined to create the global configuration object. This configuration object will then be available on each server request. This can be illustrated by starting your Front-Commerce server in development mode. If your server is running on `http://localhost:3000` and you open the URL [`/__front-commerce/debug`](http://localhost:3000/__front-commerce/debug), you will have a dump of the configuration for this specific request under the section `config`. ```json { "allShops": { "store:default": { "id": "default", "url": "http://localhost:3000", "locale": "en-GB", "magentoStoreCode": "default", "currency": "EUR" }, "store:fr": { "id": "fr", "url": "http://fr.localhost:3000", "locale": "fr-FR", "magentoStoreCode": "fr", "currency": "EUR" } }, "currentShopId": "default", "shop": { "id": "default", "url": "http://localhost:3000", "locale": "en-GB", "magentoStoreCode": "default", "currency": "EUR" }, "cache": { "defaultMaxBatchSize": 100, "strategies": [ { "implementation": "Redis", "supports": "*", "disabledFor": [], "config": { "host": "localhost" } } ] }, "contentSecurityPolicy": { "__dangerouslyDisable": false, "directives": { "scriptSrc": [], "frameSrc": [], "styleSrc": [], "imgSrc": [], "fontSrc": [], "connectSrc": [], "frameAncestors": [], "baseUri": [] }, "reportOnly": { "scriptSrc": false, "frameSrc": false, "styleSrc": false, "imgSrc": false, "fontSrc": false, "frameAncestors": false, "connectSrc": false } }, "cors": { "origin": { "referal-0": "http://magento23.test" } }, "device": { "memoizationMaxAge": 60000, "type": "pc", "viewportWidthInPx": 1400 }, "public": { "analytics": { "disableDevWarning": false }, "deprecations": { "ignore": "", "trace": "" }, "compatEnv": { "FRONT_COMMERCE_WEB_DEV_ANALYTICS_WARNING_DISABLE": "true" }, "password": { "disableHint": false } "shop":{ "id": "default", "url": "http://localhost:3000", "locale": "en-GB", "currency": "EUR" } }, "magento": { "endpoint": "http://magento23.test", "version": "2", "proxiedPaths": [] } } ``` :::tip When the `FRONT_COMMERCE_ENV` environment is not set to `production`, for example in a staging environment, the configuration will still be available in the `__front-commerce/debug` page, but the page will be secured with a token configurable with the `FRONT_COMMERCE_DEBUG_TOKEN` environment variable. Then you can access the endpoint with the token in the URL: `/__front-commerce/debug?token=your-token`. ::: ## Configuration provider definition In practice, a configuration provider is an object with five properties: a `name`, a `schema`, static `values` (available independently from the request), a `slowValuesOnEachRequest` function to resolve values depending on the request and a `fetchRemoteConfiguration` function to fetch values remotely. ```js const serviceConfigurationProvider = { name, schema, values, slowValuesOnEachRequest, fetchRemoteConfiguration, }; ``` See the sections below to understand what each key stands for. export function Label({ children }) { return ( {children} ); } ### `name` The identifier of the configuration provider. This is needed for configuration providers' registration. See [Inject a configuration provider](#inject-a-configuration-provider) for more details. ```js const name = "serviceProvider"; ``` ### `schema` It's a function returning an object representing the definition of the fields that will appear in the global configuration object if the configuration provider is registered. It can define things like field formats, default values or environment variables. The schema definition is based on [convict](https://github.com/mozilla/node-convict), a library developed by Mozilla to validate configurations. For a single field, the schema will have these keys: - `doc` (string): A description of the field and pointers to learn how to get its value if it requires a manual operation - `format` (string, array or function): The formatter used for this field's value. See [how validation works in convict](https://github.com/mozilla/node-convict#validation). - `default` (any): A default value. If you don't have a default value, you still have to set one by using the `null`. If there is no default value, it won't be considered as a field definition. - `env` (string, optional): The name of the environment variable that should be used as the value. If none is given, the configuration won't be configurable by environment. Please keep in mind that environment variables should still match [Front-Commerce's naming convention](/docs/2.x/reference/environment-variables#add-your-own-environment-variables). Thus, if we want to define a configuration named `serviceKey` available in `req.config.serviceKey` that would take its value from the environment variable `FRONT_COMMERCE_SERVICE_KEY`, we would use this schema definition: ```js const schema = () => ({ serviceKey: { doc: "The key to get access to our remote service", format: String, default: null, env: "FRONT_COMMERCE_SERVICE_KEY", }, }); ``` A configuration provider's schema is not limited to a single field though. You can set multiple configuration keys but also nest deeper objects. For instance, if we want to group a `key` and a `secret` into a single `service` key, we would write the following schema: ```js const schema = () => ({ service: { key: { doc: "The key to get access to our remote service", format: String, default: null, env: "FRONT_COMMERCE_SERVICE_KEY", }, secret: { doc: "The secret to get access to our remote service", format: String, default: null, env: "FRONT_COMMERCE_SERVICE_SECRET", }, }, }); ``` You could then access the values with `req.config.service.key` or `req.config.service.secret`. Please note that if another configuration provider's schema also defined a `service` key, it would merge the definitions and in your final `req.config.service` you would have both the keys from the other configuration provider's schema and from the above schema. ### `values` Most of the time `default` values in the schema is sufficient. However, in some cases you may need to fetch some values from an API, a dynamic file, etc. This is what `values` is for. It is an optional promise that should return the missing values in your schema. It will override default values and env values from the schema with the new values. However only keys from the `values` result will take precedence, the default values and env values will be kept for other keys. For instance, if we implemented the following `values` promise, the `secret` would still be `process.env.FRONT_COMMERCE_SERVICE_SECRET` from the above schema. ```js const values = fetch("https://api.example.com/my-service-key") .then((response) => response.json()) .then((key) => ({ service: { key: key, }, })); ``` Please note that this promise is launched only once on server bootstrap. If the configuration changes over time on your API, the `req.config.service.key` value will still be the same. If it needs to change over time, please use `slowValuesOnEachRequest` or `fetchRemoteConfiguration` instead. ### `slowValuesOnEachRequest` :::note `slowValuesOnEachRequest` is a low level API in Front-Commerce. You shouldn't be need it in most cases. ::: `slowValuesOnEachRequest` is a function that extracts configuration values from the current request. For instance, depending on the URL, the configuration `currentShopId` will get a different id and thus display different information. ```js const slowValuesOnEachRequest = (req) => { const url = req.originalUrl; const shopId = getShopIdFromUrl(url); return { currentShopId: shopId, }; }; ``` :::caution This part is named `slowValuesOnEachRequest` because we want to stress the fact that it can have a huge impact on your website performance. Avoid its usage as much as you can and try to use `values` instead. If this is the only way to setup your configuration make sure to memoize its result to limit the performance impact as much as possible. ```js import memoize from "lodash/memoize"; const getShopIdFromHostname = memoize((hostname) => { /* The definition of the `currentShopId` variable should live here */ return { currentShopId: currentShopId, }; }); const slowValuesOnEachRequest = (req) => { const hostname = req.hostname; return getShopIdFromHostname(req.hostname); }; ``` ::: ### `fetchRemoteConfiguration` :::note `fetchRemoteConfiguration` is a low level API in Front-Commerce. You shouldn't need it in most cases. ::: `fetchRemoteConfiguration` is a function that is called at a later stage in Front-Commerce request handling cycle to receive a fully initialized `request` object, so that, for instance, [you can instantiate a loader to retrieve some configuration from Magento](https://gitlab.blackswift.cloud/front-commerce/front-commerce/-/commit/f57ccabae32ebe6243fc213485078cb1f98f8a30#9e3c152a167c50222b152728db1b5946d409ba89_0_29). :::caution Like `slowValuesOnEachRequest`, `fetchRemoteConfiguration` can have a huge impact on the performances. If you really need to implement it, please make sure to memoize its result to limit the performance impact as much as possible. ::: ## Inject a configuration provider Assuming that we have defined the following configuration provider: ```ts title="./config-providers/acmeConfigProvider.ts" export default { name: "acme-config", schema: () => ({ service: { key: { doc: "The key to get access to our remote service", format: String, default: null, env: "FRONT_COMMERCE_SERVICE_KEY", }, secret: { doc: "The secret to get access to our remote service", format: String, default: null, env: "FRONT_COMMERCE_SERVICE_SECRET", }, }, }), }; ``` ### From your application configuration You can add the configuration to your [`front-commerce.config.ts`](../../04-api-reference/front-commerce-core/config.mdx) file. ```ts title="front-commerce.config.ts" import { defineConfig } from "@front-commerce/core/config"; import themeChocolatine from "@front-commerce/theme-chocolatine"; // add-next-line import acmeConfigProvider from "./config-providers/acmeConfigProvider"; export default defineConfig({ extensions: [themeChocolatine()], // add-start configuration: { providers: [acmeConfigProvider], }, // add-end }); ``` ### From an extension Alternatively, you can add a configuration provider from an extension in the [extensions definition](../../04-api-reference/front-commerce-core/defineExtension.mdx). ```ts title="./acme-extension.ts" import { defineExtension } from "@front-commerce/core"; // add-next-line import acmeConfigProvider from "./config-providers/acmeConfigProvider"; export default defineExtension({ name: "acme-extension", // add-start configuration: { providers: [acmeConfigProvider], }, // add-end }); ``` :::info You can learn more about extensions in the [Register an extensions](../register-an-extension.mdx) guide. ::: --- # Extend and read public configurations URL: https://developers.front-commerce.com/docs/3.x/guides/configuration/extend-and-read-public-configurations # Public Configuration{frontMatter.description}
## Extending the public configuration To extend the public configuration please ensure you have read the [Add a configuration provider](/docs/3.x/guides/configuration/adding-a-configuration-provider) section. The public configuration can be extended by [Adding a configuration provider](/docs/3.x/guides/configuration/adding-a-configuration-provider) which exposes a `public` object in the schema, for example: ```ts title="./my-extensions/acme-extension/configProvider.ts" export default { name: "acme-config", schema: () => ({ // it's import to extend the `public` object public: { acmeValue: { doc: "The public api key for ACME", format: String, default: undefined, env: "FRONT_COMMERCE_WEB_ACME_PUBLIC_KEY", }, }, }), }; ``` You can then add this to your [extension definition](/docs/3.x/api-reference/front-commerce-core/defineExtension): ```ts title="./my-extensions/acme-extension/index.ts" import configProvider from "./configProvider"; import { defineExtension } from "@front-commerce/core"; export default defineExtension({ name: "acme", theme: "./extensions/acme/theme", // add-start configuration: { providers: [configProvider], }, // add-end }); ``` ## Reading the custom public configuration You should now be able to access the value from the client or server as any other public configuration value. ### From the Client To access the public configuration from the client you can use the [`usePublicConfig`](/docs/3.x/api-reference/front-commerce-core/react#usepublicconfig) hook, or the [`getPublicConfig`](/docs/3.x/api-reference/front-commerce-core/react#getpublicconfig) function. - The [`usePublicConfig`](/docs/3.x/api-reference/front-commerce-core/react#usepublicconfig) hook is mainly used to access the public configuration from a React component. - The [`getPublicConfig`](/docs/3.x/api-reference/front-commerce-core/react#getpublicconfig) function is used to access the public configuration from a non-React component. :::tip advanced We additionally attached the public configuration to the `window.__FRONT_COMMERCE__.publicConfig` object. ::: ```tsx title="./my-extensions/acme-extension/theme/components/MyComponent.tsx" import { usePublicConfig } from "@front-commerce/core/react"; const MyComponent = () => { const { acmeValue } = usePublicConfig(); returnACME value: {acmeValue}
;
};
```
### From the Server
You can access the public configuration from the server using the config from
your
[FrontCommerceApp](/docs/3.x/api-reference/front-commerce-remix/front-commerce-app#appconfig)
```ts title="./app/routes/my-route.ts"
import type { LoaderFunctionArgs, ActionFunctionArgs } from "@remix-run/node";
import { FrontCommerceApp } from "@front-commerce/remix";
export const loader = ({ context }: LoaderFunctionArgs) => {
// highlight-start
const app = new FrontCommerceApp(context.frontCommerce);
const acmeValue = app.config.public.acmeValue;
// highlight-end
// do something
};
export const action = ({ context }: ActionFunctionArgs) => {
// highlight-start
const app = new FrontCommerceApp(context.frontCommerce);
const acmeValue = app.config.public.acmeValue;
// highlight-end
// do something
};
```
### From GraphQL resolvers
You can access the public configuration from your GraphQL resolvers:
```ts title="./app/graphql/resolvers/my-resolver.ts"
import type { FrontCommerceContext } from "@front-commerce/core";
import type { MyResolverArgs } from "../types";
export default {
Query: {
myResolver: async (parent, args, context, info) => {
// highlight-next-line
const acmeValue = context.config.public.acmeValue;
// do something
},
},
};
```
---
# Accessing current shop configuration
URL: https://developers.front-commerce.com/docs/3.x/guides/configuration/accessing-current-shop-configuration
## From the Client (_Public_)
The current shop configuration can be accessed from the client using the
[public configuration](./02-extend-and-read-public-configurations.mdx).
:::note
The public shop configuration (`config.public.shop`) is a subset of the private
shop configuration (`config.shop`).
This will only contain information that can be exposed to the client.
:::
```mdx-code-block
{shop.id}
{shop.locale}
{frontMatter.description}
## What is a store in Front-Commerce A store in Front-Commerce has the same meaning as [in Magento](https://experienceleague.adobe.com/en/docs/commerce-admin/stores-sales/site-store/stores). Usually, the goal of a store is to display your catalog in multiple languages. If you want to adapt the prices depending on your language, you should use the websites feature. ## Configuring multiple stores A single of Front-Commerce can handle several stores at the same time. This is configurable in `app/config/stores.js`. :::note However, if you need multiple websites, you will need to deploy as many Front-Commerce instances as there are websites. Feel free to{component}
;
}
return component;
}}
/>
);
}
```
:::tip
You can also use the
[`useCompositionComponentMap`](../../04-api-reference/front-commerce-core/react.mdx#usecompositioncomponentmap)
hook to get the individual composition components and build your own rendering
logic:
```tsx
const SharedContent = useCompositionComponentMap("SharedContent");
// {frontMatter.description}
In Front-Commerce we have separated our components in two categories: the [**UI** components](./create-a-ui-component) available in the `app/theme/components` folder, and the **Business** components available in the `app/theme/modules` and `app/theme/pages` folders. :::note If you would like to understand why we went for this organization, feel free to refer to [React components structure](../concepts/react-components-structure/) first. ::: ## What is a Business component A Business component will be located in the `app/theme/modules` folder. Those components are not meant to be reused a lot in your application, they are built with a **very specific use in mind**. When creating a custom theme, they should emerge in [your Pages components](../get-started/your-first-route/). To illustrate this, imagine that you are building the homepage for your store. You add a big hero image on top, some product listings for news and sales, a reinsurance banner, etc. Quickly, you will want to **extract** some components from your page to avoid a _big bloated file_. Some of these components will be extracted as **reusable UI components** but some are very specific to your page and there is no reason to put them in the [`components`](./create-a-ui-component) folder. :::note They are often a mix between UI components and custom layout. They may be split into multiple components if they are big enough. ::: Generally, they are related to **your business** and often need backend data like CMS content or store information. We refer to them as **Business components** or even **modules**. :::note Unlike UI components, Business components are often _smart_ and contain logic. We try to extract this logic in **hooks**, but more on that later. ::: ## Creating a store locator To explain the concept and the emergence of modules, we will add a **store locator** to our home page and see how to extract it properly as a module. In the following steps, we are going to build our store locator and we will go through: 1. Displaying a map on the homepage 2. Fetching the position of the store from the backend 3. Link both to have an actual module
{/* ... The rest of the homepage */}
My awesome store is HERE!
);
// ...
```
With that, you should see the map appear in your homepage.
{/* TODO: Uncomment when the CSP article is written */}
{/* :::warning Important */}
{/* You will detect issues with remote assets (images, CSS…) not being loaded. It is */}
{/* related to the default CSP headers */}
{/* sent by Front-Commerce. To allow new domains, you should modify your */}
{/* [`config/website.js`'s `contentSecurityPolicy` key](/docs/2.x/reference/content-security-policy) */}
{/* (i.e: define `imgSrc: ["*.openstreetmap.org"]`). */}
{/* ::: */}
Loading...
;
}
if ((!loading && !store) || error) {
return Oops, an error occurred.
;
}
const coordinates = [store.coordinates.longitude, store.coordinates.latitude];
const defaultZoom = 14;
return (
My awesome store ─ {props.store.name}
Email: {props.store.owner.email}
Phone: {props.store.phone}
{/* ... */}
);
```
As you can see, we did not use a relative import. This is because in
Front-Commerce we have a few aliases that will let you import files without
worrying about your current position in the folder structure.
In our case, the `Home` component being in `app/theme/pages/Home/Home.js`, we do
not have to import the `StoreLocator` by using relative paths
`../../modules/StoreLocator` but we can remain with
`app/theme/modules/StoreLocator` which is more explicit. This is possible for
any file located in the folder `theme/theme` of an extension.
And it works! You now have a clean `Home` page component that uses a Business
component which could be used anywhere in your application (About us, Contact,
etc.).
:::info Going further
The store locator we just created is very simple and it has a very limited
Business impact. The store locator module does not need to know the
implementation of the map itself (like the fact of using `react-leaflet`). So a
map component could be extracted in a **UI** component. But for the sake of this
guide, we kept it simple.
:::
As a final note, please keep in mind that splitting code is a difficult task. It
needs practice and refinement. But it is also a pretty personal point of view.
Thus one team could split code differently. In this guide we have made a choice
but feel free to make yours.
In any case, we advice you to not overcomplicate things and find a method that
matches your needs.
---
# Create a custom image adapter
URL: https://developers.front-commerce.com/docs/3.x/guides/create-a-custom-image-adapter
{frontMatter.description}
An Image Adapter is a custom function that you can use to deliver enhanced and optimized images for every user with your custom adapter. It is a function that takes an image URL as input and returns a new image URL as output. The new image URL can be the same as the original image URL, or it can be a different image URL that is optimized for the user's device, browser, or network. ## Getting Started To get started, you need to create a custom adapter class. The class must extend the `ImageAdapter` domain which implements a `supportSrc` method, and a `makeImageSrc` method. The `supportSrc` method is used to check if the image URL is valid for the current adapter. If the image URL is valid, the `makeImageSrc` method is called to generate the new image URL. ### Creating an Image Adapter Let's create two Image adapters that extends the base `ImageAdapter` class and implements two key methods: `supportSrc` for URL validation and `makeImageSrc` for URL transformation. For this example, we will create adapters for two popular image services: Unsplash and Lorem Picsum. First, let's look at an adapter for Unsplash images: ```typescript title="my-extension/adapters/unsplash.ts" import { ImageAdapter } from "theme/components/atoms/Image/ImageAdapter"; class UnsplashAdapter extends ImageAdapter { supportSrc(src: string) { return src.includes("unsplash.com"); } makeImageSrc(src: string) { // ... do something with the image URL return src; } } export default new UnsplashAdapter(); ``` And here's a similar adapter for Lorem Picsum: ```typescript title="my-extension/adapters/lorem-picsum.ts" import { ImageAdapter } from "theme/components/atoms/Image/ImageAdapter"; class LoremPicsumAdapter extends ImageAdapter { supportSrc(src: string) { return src.includes("picsum.photos"); } makeImageSrc(src: string) { // ... do something with the image URL return src; } } export default new LoremPicsumAdapter(); ``` ### Registering an Image Adapter To register an Image Adapter, you need to add it to the `imageAdapters` component. You can do this by adding it to a top level route or a layout for example. ```typescript title="my-extension/routes/_main.tsx" // Other imports ... // add-start import imageAdapters from "theme/components/atoms/Image/adapters"; import UnsplashAdapter from "./adapters/unsplash"; import LoremPicsumAdapter from "./adapters/lorem-picsum"; // add-end // Original route code ... export default function MainLayout() { const { headerNavigationMenu, footerNavigationMenu } = useLoaderData{frontMatter.description}
import Figure from "@site/src/components/Figure"; In Front-Commerce components are classified under two categories: the **UI** components available in the `theme/components` folder, and the **Business** components {/* TODO: add link to article */} available in the `theme/modules` and `theme/pages` folders. :::info If you feel the need to understand why we went for this organization, feel free to refer to [React components structure](../05-concepts/react-components-structure.mdx) first. ::: As mentioned in the introduction, we will use Storybook {/* TODO: add link to article */} in the process because it is our usual workflow when creating a UI Component. But if you don't need it or prefer to add your stories later, feel free to leave the parts mentioning Storybook later. Front-Commerce’s core UI components follow the same principles and you could dive into the [`node_modules/@front-commerce/theme-chocolatine/theme/components`](https://gitlab.blackswift.cloud/front-commerce/front-commerce/-/tree/main/packages/theme-chocolatine/theme/components) folder to find examples into our source code. But first, let's define what is an ideal UI Component. ## The ideal UI Component In Front-Commerce we call UI component any component that is: - **Reusable in many contexts**: if a component is used only once in the whole application, it might feel like it doesn't exist purely for UI purposes. The component most likely needs to be moved to the `/app/modules` folder {/* TODO : add Create a business component link */}. That's also the reason why we avoid to give names too close to its business use. For instance, we don't want to have a UI component that would be called `ProductDescription`. It would be better to go for a `Description` that would thus be reusable by a Category. - **Focused on abstracting away UI concerns**: the goal of UI components is to hide styles or [DOM](https://fr.wikipedia.org/wiki/Document_Object_Model) concerns from their parents. It may be hard to achieve sometimes, but it will greatly improve the parent component's readability. For instance, a UI component should not give the opportunity to pass a `className` in its props as it may lead to many style inconsistencies across the theme. ## How to build a UI Component? Alright, that's nice in theory, but how does it translate in practice? First, we’ll try to get a bit more tangible by creating a UI component for adding a Reinsurance Banner on a page similar to the following mockup.  ### Defining the components First, let's split the mockup in several UI components following the [Atomic Design Principles](http://atomicdesign.bradfrost.com/).  - **`app/theme/components/atoms/Typography/Heading` (green):** enforces consistent font sizes in our theme for any title - **`app/theme/components/atoms/Icon` (purple):** enforces icon sizes and accessibility guidelines - **`app/theme/components/molecules/IllustratedContent` (red):** displays some content illustrated by an image and aligns images consistently across the whole theme - **`app/theme/components/organisms/FeatureList` (orange):** manages a list of cards and inlines them, regardless of the device size. As you can see, each UI component will take place in the `app/theme/components` folder. To better understand why, please refer to our [React components structure](../05-concepts/react-components-structure.mdx) documentation. :::note If you have trouble splitting your mockups, you can refer to [Thinking in React](https://react.dev/learn/thinking-in-react) in the official React documentation or to [Brad Frost's book about Atomic Design](http://atomicdesign.bradfrost.com/). You may want to organize your code differently and that's perfectly fine. The way we splitted things here is one of many possible solutions. Such choices will depend on your project and your team. It may be a better idea to keep things simple. It's often easier to wait and see how it can be reused later. ::: We won't be able to detail each component here. We will focus on `IllustratedContent` instead. But keep in mind that any UI component in Front-Commerce will look similar to what we are going to build here. ### Setup your dev environment Before doing the actual work let's bootstrap our dev environment. To do so, you will need to create three files: - **`IllustratedContent.js` :** will bootstrap the actual component. ```tsx title="app/theme/components/molecules/IllustratedContent/IllustratedContent.tsx" const IllustratedContent = () => { returnIllustrated Content
;
};
export default IllustratedContent;
```
- **`index.js` :** will proxy the `IllustratedContent.js` file in order to be
able to do imports on the folder directly. See
[this blog post](http://bradfrost.com/blog/post/this-or-that-component-names-index-js-or-component-js/)
for more context about this pattern.
```tsx title="app/theme/components/molecules/IllustratedContent/index.ts"
import IllustratedContent from "theme/components/molecules/IllustratedContent/IllustratedContent";
export default IllustratedContent;
```
- **`IllustratedContent.stories.tsx` :** will add a story to the
[Storybook](https://storybook.js.org/) of your application. This will serve as
living documentation and will allow anyone to understand what is
`IllustratedContent` used for and how to use it.
```tsx title="app/theme/components/molecules/IllustratedContent/IllustratedContent.stories.tsx"
import type { Meta, StoryObj } from "@storybook/react";
import IllustratedContent from "./IllustratedContent";
const meta: Meta{media}
{children}
Shipping within 48h
), }; export const WithContent: Story = { name: "With a lot of content", render: () => (Shipping within 48h
Shipping within 48h
), }; ``` It has many major benefits such as: - document edge cases - provide a test suite thanks to snapshot testing ([Storyshots](https://github.com/storybooks/storybook/tree/master/addons/storyshots)) - create a common discussion base for designers, product managers, marketers, etc. {/* TODO: update [Learn more about Storybook.](./add-component-to-storybook) */} ### Use the component Once you are satisfied with your component, you can use it anywhere. In this case, the `IllustratedContent` was to be used in the Reinsurance Banner. Thus, this module's component would look like this: ```tsx import FeatureList from "theme/components/organisms/FeatureList"; import IllustratedContent from "theme/components/molecules/IllustratedContent"; import Icon from "theme/components/atoms/Icon"; import { H3 } from "theme/components/atoms/Typography/Heading"; const ReinsuranceBanner = () => (Shipping within 48h
Money back guarantee
Secured Payment
{frontMatter.description}
## Create a custom HTTP endpoint Front-Commerce is built on the top of Remix, it means that you can create custom HTTP endpoint using the [Standard Remix Routing System](https://remix.run/docs/en/main/discussion/data-flow). Routes without a default export won't serve any HTML content. You will have to use [`loader`](https://remix.run/docs/en/main/route/loader) and [`action`](https://remix.run/docs/en/main/route/action) functions to perform custom interaction with backend data. Keep in mind that `loader` is only used for `GET` requests, while `action` is used for any other request type. ### GET request example Let's create a custom HTTP endpoint to serve a simple JSON response. ```tsx title="app/routes/api.hello.tsx" import { json } from "@front-commerce/remix/node"; export async function loader() { return json({ message: "Hello, world!" }); } ``` When accessing this route, you will get a JSON response with the following content: ```bash curl http://localhost:4000/api/hello ``` ```json { "message": "Hello, world!" } ``` You can also use the standard [Javascript Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) object to send a response. ```tsx title="app/routes/api.hello.tsx" export async function loader() { return new Response("Hello World!", { status: 200, headers: { "Content-Type": "text/plain" }, }); } ``` ### POST/PUT/PATCH/DELETE request example For POST/PUT/PATCH/DELETE requests, you can use the `action` function. ```tsx title="app/routes/api.hello.tsx" export async function action({ request }: ActionFunctionArgs) { const method = request.method; return new Response(`Hey ! You've made a ${method} request !`); } ``` When acessing this route with a POST request, you will get a response with the following content: ```bash curl -X POST http://localhost:4000/api/hello ``` ``` Hey ! You've made a POST request ! ``` Or with a PUT request: ```bash curl -X PUT http://localhost:4000/api/hello ``` ``` Hey ! You've made a PUT request ! ``` You can leverage this endpoint to perform any custom interaction you need, here are some example of things you can do with these: - Serve content from the filesystem. ```ts title="app/routes/get-document.tsx" import fs from "node:fs"; export async function loader() { const file = fs.readFileSync("/home/server/myfile.pdf"); return new Response(file); } ``` - Return computed data like time ```ts title="app/routes/get-time.tsx" import { json } from "@front-commerce/remix/node"; export async function loader() { return json({ time: new Date().toISOString() }); } ``` - Serve data from a remote API ```ts title="app/routes/get-data.tsx" import { json } from "@front-commerce/remix/node"; export async function loader() { const response = await fetch("https://jsonplaceholder.typicode.com/posts"); const data = await response.json(); return json(data); } ``` --- # Cache-Control URL: https://developers.front-commerce.com/docs/3.x/guides/customize-http-headers/cache-control{frontMatter.description}
## Overview When building a Front-Commerce application, you might need to customize routes for various reasons: - Filter out unwanted routes from extensions - Dynamically defining routes without creating files in app/routes - Renaming routes to match your business requirements (e.g., translating URLs) - Ensure only necessary API routes are available - Customize the routing behavior for your specific use case ## Basic configuration Route customization happens in your `vite.config.ts` file by providing a `defineAppRoutes` function to the Front-Commerce plugin. This function receives three parameters: - `defineRoutes`: The Remix route definition function - `extensionRoutes`: Routes defined by Front-Commerce extensions - `fileRoutes`: Routes defined in your `app/routes` directory ```ts title="vite.config.ts" export default defineConfig((env) => { return { plugins: [ remixDevTools({ client: { defaultOpen: false, }, }), frontCommerce({ env, defineAppRoutes: async (defineRoutes, extensionRoutes, fileRoutes) => { // Your custom route logic here }, }), ], }; }); ``` ## Common use cases ### Disable unused routes You can prevent specific routes from being registered by filtering them out: ```ts defineAppRoutes: async (defineRoutes, extensionRoutes, fileRoutes) => { // Remove unwanted routes from extensions const routesToDisable = ["routes/account", "routes/wishlist"]; const filteredRoutes = Object.entries(extensionRoutes).reduce( (acc, [key, route]) => { if (!routesToDisable.includes(route.id)) { acc[key] = route; } return acc; }, {} ); return filteredRoutes; }, ``` ### Create additional routes You can define new routes that don't exist in your app/routes directory: ```ts defineAppRoutes: async (defineRoutes, extensionRoutes, fileRoutes) => { return { "routes/not-in-routes-dir": { id: "routes/not-in-routes-dir", path: "/not-in-routes-dir", file: "custom/not-in-routes-dir.tsx", // This file will be created in the app/custom directory }, }; }, ``` ### Rename routes You can change the URL path of existing routes while keeping the original implementation: ```ts defineAppRoutes: async (defineRoutes, extensionRoutes, fileRoutes) => { return { "routes/wishlist": { ...extensionRoutes["routes/wishlist"], path: "/your-custom-name", // Change URL path from /wishlist to /your-custom-name }, }; }, ``` :::warning Renaming routes only changes the URL path. It does not automatically update links in your theme or components. You'll need to update those manually. ::: ## Route priority When customizing routes, keep in mind the following priority order: 1. File-based routes (app/routes/\*) 2. Programmatically defined routes (via defineAppRoutes) 3. Extension routes This means that if you define a route that conflicts with a file-based route, the file-based route will take precedence. --- # Customize the sitemap URL: https://developers.front-commerce.com/docs/3.x/guides/customize-the-sitemap{frontMatter.description}
import Figure from "@site/src/components/Figure"; It is not something that you can do in just a few minutes because your identity shines in the details. However, you can do all the heavy lifting pretty quickly by customizing what is called **Design Tokens**. And it's a great way to familiarize yourself with Front-Commerce! ## Get your Design Tokens This concept is often closely related to Design Systems. Basically Design Tokens are the _core styles_ of your design: colors, font families, font sizes, borders, shadows, etc. Together they are what make your brand unique. There even exist tools that extract those tokens from existing websites. In this example, we will use [CSS Stats](https://cssstats.com/) to extract Design Tokens from [Smashing Magazine](https://www.smashingmagazine.com/) and use them later.{frontMatter.description}
If you want to learn how the core WYSIWYG component works instead, please refer to [Display WYSIWYG content](./display-wysiwyg-content.mdx). Each platform has a specific type of WYSIWYG. This allows to change how your content is rendered depending on its origin. For instance, a content from WordPress might have some specific media shortcodes while Magento will have some widgets to display a category name. In the following section you will learn about the one implemented in Front-Commerce:Lorem ipsum…
{content}
{frontMatter.description}
## What is dynamic routing? Dynamic routes are generated based on the data available in your application, allowing for more meaningful and SEO-friendly URLs. For example, instead of a generic URL such as `/product/sku-6`, you can have a more descriptive URL like `/acme-product.html`. Consider a Remix route for your products defined as `routes/product.$id.tsx`. By leveraging dynamic routes, you can replace generic product URLs with SEO-friendly alternatives. #### Generic Route Example - URL: `/product/sku-6` #### SEO-Friendly Route Example - URL: `/acme-product.html` By implementing dynamic routes, you enhance the readability and search engine optimization (SEO) of your URLs, which can improve your site's visibility and user experience. ## How to create dynamic routes?Product: {data.product.name}
;
}
```
{frontMatter.description}
## What is a layout route? Layout routes are used to apply a the same layout to multiple pages, generally these are pathless routes. For more information how routing works in Remix, please see the [Nested Routes](https://remix.run/docs/en/main/file-conventions/routes#nested-routes) documentation. In Front-Commerce some of the main layout routes are: - [`_main.tsx`](https://gitlab.blackswift.cloud/front-commerce/front-commerce/-/blob/main/packages/theme-chocolatine/routes/_main.tsx) - [`_main.user.tsx`](https://gitlab.blackswift.cloud/front-commerce/front-commerce/-/blob/main/packages/theme-chocolatine/routes/_main.user.tsx) - [`_main.user.orders.tsx`](https://gitlab.blackswift.cloud/front-commerce/front-commerce/-/blob/main/packages/theme-chocolatine/routes/_main.user.orders.tsx) - [`checkout.tsx`](https://gitlab.blackswift.cloud/front-commerce/front-commerce/-/blob/main/packages/theme-chocolatine/routes/checkout.tsx) To extend these routes you can either create your own layout route or re-use an existing one. ## Create a new layout route To create a new layout route you can create a new file in the `routes` folder ```tsx title="routes/_main.tsx" import { Outlet } from "@remix-run/react"; const Layout = () => { return ({frontMatter.description}
When developing an e-commerce store, you might at some point need to expose new data in your unified GraphQL schema to support new features and allow frontend developers to use them. Front-Commerce’s GraphQL modules is the mechanism allowing to extend and override any part of the schema defined by other modules. The Front-Commerce core and platform integrations (such as Magento2) are implemented as GraphQL modules. They leverage features from the GraphQL Schema Definition Language (SDL). This page will guide you through the process of exposing a new feature in your GraphQL schema. We will create an extension with a GraphQL module that allows to maintain a counter of clicks for a product. ## Create an extension To extend the GraphQL schema and implement your own logic, you first have to create an extension. An extension can be created by adding a new folder under `extensions` and by creating a `index.ts` file (the extension definition) with the following content: ```typescript title="example-extensions/click-counter/index.ts" import { defineExtension } from "@front-commerce/core"; export default function clickCounter() { return defineExtension({ name: "click-counter", meta: import.meta, }); } ``` Then you need to [register the extension into your Front-Commerce project](./register-an-extension.mdx). ## Add a GraphQL module within the extension For now, the `click-counter` extension does not provide any feature. To extend the GraphQL schema and implement our own logic, we need to add a GraphQL module to the extension containing a schema and some resolvers.{frontMatter.description}
:::tip You can check the [`example-extension/mdx-blog`](https://gitlab.blackswift.cloud/front-commerce/front-commerce/-/tree/main/skeleton/example-extensions/mdx-blog) example to see how MDX can be implemented. ::: ## Setup ### Install MDX bundler for vite ```sh pnpm add @mdx-js/rollup @mdx-js/react ``` ### Update `vite.config.ts` **Please note that `mdx` plugin must be declared before the `frontCommerce` plugin** to ensure that MDX files have already been transformed to standard React components before going through the Front-Commerce–Remix–React toolchain. ```diff import { defineConfig } from "vite"; import { vitePlugin as frontCommerce } from "@front-commerce/remix/vite"; +import mdx from "@mdx-js/rollup"; export default defineConfig((env) => { return { plugins: [ + mdx({ providerImportSource: "@mdx-js/react" }), frontCommerce({ env }) ], }; }); ``` ## Adding custom components To specify which component to render for a specific tag, you can use the `MDXProvider`, please check out [demo example](https://gitlab.blackswift.cloud/front-commerce/front-commerce/-/blob/main/skeleton/example-extensions/mdx-blog/routes/_main.blog.tsx#L8) to see how to use it. ## Demo You can load this demo extension to check if your setup is working by adding these lines to your `front-commerce.config.ts` file: ```diff import { defineConfig } from "@front-commerce/core/config"; import themeChocolatine from "@front-commerce/theme-chocolatine"; import storesConfig from "./app/config/stores"; import cacheConfig from "./app/config/caching"; import rateLimiterConfig from "./app/config/rateLimiter"; import appCSPProvider from "./app/config/cspProvider"; import serverEventsConfig from "./app/config/serverEvents"; import pwaConfig from "./app/config/pwa"; +import mdxBlog from "./example-extensions/mdx-blog"; export default defineConfig({ extensions: [ themeChocolatine(), + mdxBlog() ], stores: storesConfig, cache: cacheConfig, rateLimiter: rateLimiterConfig, serverEvents: serverEventsConfig, configuration: { providers: [appCSPProvider()], }, v2_compat: { useApolloClientQueries: true, useFormsy: true, }, pwa: pwaConfig, }); ``` Then run your Front-Commerce app and go to [http://localhost:4000/blog](http://localhost:4000/blog) ## References - https://mdxjs.com/docs/ - https://mdxjs.com/packages/rollup/ --- # Remix Development Tools URL: https://developers.front-commerce.com/docs/3.x/guides/extend-the-vite-configuration/remix-development-tools{frontMatter.description}
Since Front-Commerce is based on Remix, you can use any related Remix extension to enhance your development experience and your project. In this guide, we will guide you through the setup of [Remix Development Tools](https://remix-development-tools.fly.dev/). :::tip Remix Development Tools isn't affiliated with Front-Commerce. Since we use it to work on Front-Commerce, we decided to share it with you to enhance your experience too! ::: ## Quick start ### Install the extension ```sh pnpm add --save-dev remix-development-tools ``` ### Add the extension to your `vite.config.ts` **Please note that `remixDevTools` plugin must be declared before the `frontCommerce` plugin** ```diff import { defineConfig } from "vite"; import { vitePlugin as frontCommerce } from "@front-commerce/remix/vite"; +import { remixDevTools } from "remix-development-tools"; export default defineConfig((env) => { return { plugins: [ + remixDevTools({ + client: { + defaultOpen: false, + }, + }), frontCommerce({ env }) ], }; }); ``` --- # Tailwind URL: https://developers.front-commerce.com/docs/3.x/guides/extend-the-vite-configuration/tailwind{frontMatter.description}
:::tip You can check the [`example-extension/tailwind`](https://gitlab.blackswift.cloud/front-commerce/front-commerce/-/tree/main/skeleton/example-extensions/tailwind) example to see how tailwind can be implemented. ::: ## Install Tailwind ```sh pnpm add -D tailwindcss ``` ## Generate Tailwind configuration ```sh pnpm dlx tailwindcss init -p --ts ``` ## Update your tailwind config Update your `tailwind.config.ts` to include files from `app/theme`: ```diff import type { Config } from 'tailwindcss' export default { - content: [] + content: ["./app/**/*.{ts,tsx,js,jsx}"], theme: { extend: {}, }, plugins: [], } satisfies Config ``` If you have components in some of your extensions, you need to add the related extension paths to the `content` directive. ## Setup PostCSS Add the `tailwindcss` directive to the `postcss.config.js` file: ```diff export default { plugins: { autoprefixer: {}, + tailwindcss: {}, }, }; ``` ## Inject Tailwind stylesheet Create a `tailwind.css` file in the `app` folder with the following content: ```css @tailwind base; @tailwind components; @tailwind utilities; ``` Then, import this file in your `root.tsx` like so: ```diff ... + import "./tailwind.css"; ... ``` You can now start your project and tailwind will be used for all your styles. # Usage You can test it by loading this module into your app by inject it in your `front-commerce.config.ts` file: ```diff ... +import tailwind from "./example-extensions/tailwind"; export default defineConfig({ extensions: [ themeChocolatine(), + tailwind() ], ... ``` And update the `tailwind.config.js` with this: ```diff /** @type {import('tailwindcss').Config} */ export default { content: [ "./app/theme/**/*.{ts,tsx,js,jsx}", + "./example-extensions/tailwind/theme/**/*.{ts,tsx,js,jsx}", ], theme: { extend: {}, }, plugins: [], } ``` Now you can head to [`http://localhost:4000/tailwind`](http://localhost:4000/tailwind) and check that Tailwind is working. ## References - https://tailwindui.com/documentation - https://tailwindcss.com/docs/guides/remix --- # Components Map URL: https://developers.front-commerce.com/docs/3.x/guides/extension-features/components-map{frontMatter.description}
For instance, component map can be useful for: - implementing a user menu with links contributed from different extensions - displaying platform-specific components in the application features specific to the platform - customizing how polymorphic GraphQL data are displayed in an application ## How to register a component map? ### Registering a new component map To register a new component map, you can use the [`registerFeature`](/docs/3.x/api-reference/front-commerce-core/extension-features#registerfeature) hook. ```ts title="./example-extension/acme-extension/index.ts" export default defineExtension({ ... unstable_lifecycleHooks: { onFeaturesInit: (hooks) => { // highlight-next-line hooks.registerFeature("acme-feature", { ui: { componentsMap: { // This should resolve to a valid file relative to the current import.meta.url // highlight-next-line Header: new URL("./components/AcmeHeader.tsx", import.meta.url), Toolbar: new URL("./components/AcmeToolbar.tsx", import.meta.url), Footer: new URL("./components/AcmeFooter.tsx", import.meta.url), }, }, }); }, }, }); ``` ### Override an existing component map Let's say our application needs to disable the previously registered `Toolbar` component which is by default registered in the `acme-extension`. We can achieve this by registering a new component map with the same name, but replacing the `Toolbar` with `null` ```ts title="./example-extension/application-extension/index.ts" export default defineExtension({ ... unstable_lifecycleHooks: { onFeaturesInit: (hooks) => { // this will extend the `acme-feature` from `acme-extension` hooks.registerFeature("acme-feature", { ui: { // we only override the `Toolbar` component, the others will still resolve from `acme-extension` // highlight-next-line componentsMap: { Toolbar: null }, }, }); }, }, }); ``` :::tip When overriding an existing component map, the last registered extension will be the components used for the feature. All the components are merged together. Not including a component, will maintain the component registered before. To _unregister_ it, you must explicitly override it with `null`. So in the above example, the final components map will be resolved as: ```ts { Header: AcmeHeader, Toolbar: () => null, Footer: AcmeFooter, } ``` ::: ## How to use the components map? The components map is used through the [`useExtensionComponentMap`](/docs/3.x/api-reference/front-commerce-core/react#useextensioncomponentmap) hook. ```tsx import { useExtensionComponentMap } from "@front-commerce/core/react"; const App = () => { const AcmeFeature = useExtensionComponentMap("acme-feature"); return ({frontMatter.description}
For instance feature flags can be useful for display or not a banner in your application. ## Using feature flags ### Declaring a feature flag To declare a feature flag, you must include a `featureFlags` property in your extension declaration. ```ts title="extension/acme/index.ts" export default defineExtension({ ... unstable_lifecycleHooks: { onServerServicesInit: async (services, _request, config, user) => { onFeaturesInit: (hooks) => { hooks.registerFeature("order", { flags: { canOrderFooBar: true, } }); } }, } ... ``` This example will allow you to know if you can order a `FooBar` product. ### Using a feature flag To use a feature flag, you must use the `useExtensionFeatureFlags` hook. The `useExtensionFeatureFlags` hook takes three arguments: - The extension name - The feature flag name - The default value ```tsx title="extension/acme/pages/OrderFooBarPage.tsx" import { useExtensionFeatureFlags } from "@front-commerce/core/react"; export function OrderFooBarPage() { const canOrderFooBar = useExtensionFeatureFlags( "order", "canOrderFooBar", false ); return (Order FooBar
{canOrderFooBar ? ( ) : (You cannot order FooBar
)}{frontMatter.description}
## When to use flash messages? Flash messages are used to display informations to the user. These messages are meant to be displayed once and are stored in the session. When consumed, they are removed from the session. ## Flash message data type Flash messages are represented by an object the following properties: | Property | Type | Description | | --------- | ------ | -------------------------------------------------------------------------------------------------------------------------------- | | `type` | string | The type of the flash message. It can be one of the types declared in the [flash messages component](#flash-messages-component). | | `message` | string | The message to display. | | `data` | object | An object that can be used to pass additional data to the endering component. | ## Flash messages component The default theme provides a default implementation for flash messages depending on the `type` property of the flash message object. It can be customized by overriding the [`theme/modules/FlashMessages/getFlashMessageComponent.tsx`](https://gitlab.blackswift.cloud/front-commerce/front-commerce/-/blob/9cc7010e5d3c3ade454cdeaad90f28c769916695/packages/theme-chocolatine/theme/modules/FlashMessages/getFlashMessageComponent.jsx) file. ## Adding flash messages Flash messages can be added in your code from the user session object. Here's an example on how to do it in a route loader via the `FrontCommerceApp` instance: ```typescript import { FrontCommerceApp } from "@front-commerce/remix"; export const action = async ({ context }: ActionFunctionArgs) => { const app = new FrontCommerceApp(context.frontCommerce); app.user.session.addFlashMessage({ type: "success", message: "Payment succeeded", }) //... }); ``` ## Consume flash messages Flash messages can be consumed in your code from the user session too. They usually are returned like any other data in a route loader: ```tsx import { FrontCommerceApp } from "@front-commerce/remix"; import { json } from "@front-commerce/remix/node"; export const loader = async ({ context }: LoaderFunctionArgs) => { const app = new FrontCommerceApp(context.frontCommerce); const flashMessages = app.user.session.getFlashMessages(); return json({ flashMessages }); }); ``` ## Flash message component In the default theme, we provide a ready-to-use flash message component. It can be used to display flash messages. Here is an usage example: ```typescript import { FrontCommerceApp } from "@front-commerce/remix"; import { json } from "@front-commerce/remix/node"; export const loader = async ({ context }: LoaderFunctionArgs) => { const app = new FrontCommerceApp(context.frontCommerce); const flashMessages = app.user.session.getFlashMessages(); return json({ flashMessages }); }); export default PaymentPage() { const { flashMessages } = useLoaderData
setComments(event.target.value)}
value={comments}
type="text"
/>
{
onAuthorize(gscAccepted ? { comments } : null);
}}
error={error}
/>
);
};
export default CustomComponent;
```
There are a few things to understand here:
- The `SubmitPayment` component is a common component across all payment methods
to ensure consistency in how methods are managed.
- `method` the current selected method.
- `value` contains initial additional data (usually it is always null).
- `onAuthorize` should be called with the additional data on `
setComments(event.target.value)}
value={comments}
type="text"
/>
{BaseComponent ? (
{
onAuthorize({ ...additionalData, comments });
}}
value={value}
gscAccepted={gscAccepted}
error={error}
method={method}
/>
) : (
{
onAuthorize(gscAccepted ? { comments } : null);
}}
error={this.props.error}
/>
)}
);
};
export default CustomEnhancer;
```
{frontMatter.description}
> We will keep improving this page over time. ## Resources - https://webperf.tools/ - [Web Vitals (official documentation page)](https://web.dev/vitals/) - [Everything we know about Core Web Vitals and SEO](https://simonhearne.com/2021/core-web-vitals-seo) - Understanding the [Chrome User Experience Report (CrUX)](https://developers.google.com/web/tools/chrome-user-experience-report/) - An analysis of CrUX data: [What do Lighthouse Scores look like across the web?](https://www.tunetheweb.com/blog/what-do-lighthouse-scores-look-like-across-the-web/) - [Three Techniques for Performant Custom Font Usage](https://css-tricks.com/three-techniques-performant-custom-font-usage/) - [Detect the element associated with LCP using the DevTools](https://web.dev/optimize-lcp/#developer-tools) - Understand assets impact on different devices, to help you set budgets: [The Mobile Performance Inequality Gap, 2021](https://infrequently.org/2021/03/the-performance-inequality-gap/) ## Front-Commerce tips {/* TODO FC-XXXX drastically improve the core web vitals documentation */} {/* see EPIC https://docs.google.com/document/d/1h6Uf1H7DLYm10NYZUs300sENZnfjobMcpPoO-NwI1Es/edit?tab=t.0 */} ### Mark above-the-fold images as priority Using: `{frontMatter.description}
Enabling this feature will add a button on a product's detail page for every product that is out of stock. :::info This feature is available for Magento 1 (OpenMage LTS) and Magento 2 platforms. :::![]({require("./assets/enable-auto-refresh.gif").default})
{frontMatter.description}
## API Reference The ContributionMode instance is exposed in the `user` context, see [app.user.contributionMode](/docs/3.x/api-reference/front-commerce-remix/front-commerce-app?tab=ContributionMode#appuser) for more information. ## How to activate Contribution Mode The **Magic Button** is only visible when the **Contribution Mode** is active. One can force the contribution mode by using [Front-Commerce's `contributionMode.force` configuration](/docs/3.x/api-reference/front-commerce-core/config#contributionmode). In a default Front-Commerce application, this is achieved using the `FRONT_COMMERCE_CONTRIBUTION_MODE_FORCE` environment variable in the [`app/config/contributionMode.ts` configuration file](https://gitlab.blackswift.cloud/front-commerce/front-commerce/-/blob/update-contribution-mode-demos/skeleton/app/config/contributionMode.ts), but you can implement your own logic. :::warning This should only be used for development purposes. ::: The `ContributionMode` state should be updated using the `setContributionMode` function. ```ts user.contributionMode.setContributionMode({ enabled: true, previewMode: true, // optional and will only change if contribution mode is enabled xRayMode: true, // optional and will only change if contribution mode is enabled }); ``` Here are some examples of how to activate the **Contribution Mode**. ```mdx-code-block![]({require("./assets/enable-preview.gif").default})
![]({require("./assets/enable-x-ray.gif").default})
{aMyCustomType.name}
{frontMatter.description}
## Entering and exiting the maintenance mode The maintenance mode is activated by setting the `FRONT_COMMERCE_MAINTENANCE_MODE_FORCE_ENABLED` environment variable to `true` in your Front-Commerce project. Once that is done, any request done in your application will show the maintenance page instead. :::tip The skeleton provides an [maintenance mode demo example extension](https://gitlab.blackswift.cloud/front-commerce/front-commerce/-/tree/main/skeleton/example-extensions/maintenance-mode-demo?ref_type=heads) with three custom routes to show the interactions with the maintenance mode. ::: ## Testing and customizing the maintenance page The maintenance page can be changed by overriding the `theme/pages/Error/Maintenance.tsx` file. In order to facilitate the edition of this page, you can display it in development mode by [activating the maintenance mode](/docs/3.x/guides/maintenance-mode/entering-and-exiting-maintenance-mode). Alternatively you can navigate to the [`__front-commerce/maintenance`](http://localhost:4000/__front-commerce/maintenance) route in your application. ## Controlling Access During Maintenance To bypass the maintenance mode for certain IP addresses you can configure the `FRONT_COMMERCE_MAINTENANCE_MODE_AUTHORIZED_IPS` environment variable. Please note that you can have multiple IPs separated by a comma like: ```shell title=".env" FRONT_COMMERCE_MAINTENANCE_MODE_AUTHORIZED_IPS=127.0.0.1,83.65.12.111,2ce8:c427::7156:ad8e ``` :::caution Please configure **both v4 and v6** IP as much as possible. You can retrieve your own IP addresses with https://www.whatismyip.com/ ::: --- # Mutate Data Using Client Side Fetcher URL: https://developers.front-commerce.com/docs/3.x/guides/mutate-data-using-client-side-fetcher # Mutate Data Using Client Side Fetcher When building Front-Commerce applications with Remix, you have multiple options for handling data mutations. While the [`