Installation

Requirements

• Node.js v20+
• An active Shopify store (learn how to create one here) or a Shopify development store.
• A Sanity account (you can create one here)

In addition to these requirements, we recommend understanding the basics of React, Sanity, Remix and Hydrogen to get the most out of Fluid.

Step 1: Create a new Fluid project

Clone the Fluid repository using the following commands in your terminal:

mkdir my-fluid-app
cd my-fluid-app

# Clone the Fluid repository
npx create-remix@latest . --template frontvibe/fluid

# Create a new Sanity project
npx sanity@latest init --env .env.sanity

The npx sanity@latest command will create a new Sanity project and generate a .env.sanity file in your project directory with your SANITY_PROJECT_ID and SANITY_DATASET. You can use these variables in your .env file. More details about environment variables can be found here.

Step 2: Install the Hydrogen or Headless channel

To use Fluid, you’ll need to install the Hydrogen or Headless channel. These Shopify channels will generate access tokens to connect Fluid to your store.

The Hydrogen channel is available for all Shopify plans (Basic, Shopify, Advanced, or Plus plan). Development stores aren’t supported at this time, but you can install the Headless channel and it will work the same.

Hydrogen channel

The Hydrogen channel is required if you plan to deploy your wesbite on Oxygen (Shopify’s global hosting solution). Once you install the Hydrogen channel you’ll need to create a new storefront. We invite you to follow the official Shopify’s instructions to get started.

Headless channel

The Headless channel is the right choice if you want to use an alternative hosting solution such as Vercel. It’ll give you the exact same experience as the Hydrogen channel. You can install the Headless channel here and create a new storefront.

Once you’ve installed the channel, you’ll need to update the .env file with your access tokens. You can safely duplicate the .env.template file and name it .env.

The Public access token will be your PUBLIC_STOREFRONT_API_TOKEN and the Private access token will be your PRIVATE_STOREFRONT_API_TOKEN.

You can also replace the PUBLIC_STORE_DOMAIN with your store’s domain (xxx.myshopify.com). You can find your store’s domain in the Shopify admin dashboard > Settings > Domains.

Step 3: Update Sanity CORS

Go to your Sanity admin dashboard npx sanity@latest manage and add every hosts that we’ll need to connect to the Sanity project API. We suggest to add http://localhost:* and any production domain that you want to use. Use can use the wildcard * to allow multiple domains.

Step 4: Install the Sanity Connect app

To automatically synchronize your Shopify products and collections with your Sanity project, add the Sanity Connect app in your Shopify store. Select the Sanity project you created and the dataset.

Leave the default settings and start synchronizing:

Now, each time you add or update a Shopify product or collection, your Sanity project will be automatically updated!

Please note that the Sanity connect app won’t automatically delete products or collections that are no longer in your Shopify store. If you you to completely delete a product or a collection from your Sanity project, you’ll have to do it manually:

Step 5: Environment variables

Fluid requires the following environment variables to function properly. Some will be used by the Hydrogen app to connect to your Shopify store, and some will be used by the Sanity Studio.

NODE_ENV="development"
# Shopify
SESSION_SECRET="topSecret"
PUBLIC_STORE_DOMAIN="fluid-demo.myshopify.com"
PUBLIC_STOREFRONT_API_TOKEN="046fc93a591ca78ec9dc34657b660ac6"
PRIVATE_STOREFRONT_API_TOKEN="shpat_•••••••••••••••••••••••••"
PUBLIC_CUSTOMER_ACCOUNT_API_CLIENT_ID="shp_•••••••••••••••••••••••••"
PUBLIC_CUSTOMER_ACCOUNT_API_URL="https://shopify.com/•••••••••••••••"
PUBLIC_STOREFRONT_ID="22227"
PUBLIC_STOREFRONT_API_VERSION="2024-01"
PUBLIC_CHECKOUT_DOMAIN="checkout.frontvibe.com"
SHOP_ID="68877353204"
# Sanity
PUBLIC_SANITY_STUDIO_PROJECT_ID="gbcm3da4"
PUBLIC_SANITY_STUDIO_DATASET="production"
SANITY_STUDIO_USE_PREVIEW_MODE="true"
SANITY_STUDIO_TOKEN="•••••••••••••••••••••••••"

SESSION_SECRET

The SESSION_SECRET variable will be used to sign cookies. You should create a unique secret and add it to your .env file. It can be any random string that you can generate by yourself. More info about signing cookies in Remix can be found here.

PUBLIC_STORE_DOMAIN

The PUBLIC_STORE_DOMAIN variable will be used to connect to your Shopify store. You can find your store’s domain in the Shopify admin dashboard > Settings > Domains (xxx.myshopify.com).

PUBLIC_STOREFRONT_API_TOKEN

The PUBLIC_STOREFRONT_API_TOKEN variable will be used to connect to your Shopify store. You can find it in your Hydrogen or Headless channel.

PRIVATE_STOREFRONT_API_TOKEN

The PRIVATE_STOREFRONT_API_TOKEN variable will be used to connect to your Shopify store. You can find it in your Hydrogen or Headless channel.

PUBLIC_CHECKOUT_DOMAIN

The production shop checkout domain url.

PUBLIC_STOREFRONT_ID

The PUBLIC_STOREFRONT_ID can be found in the Shopify url of your storefront. If you installed the Hydrogen channel it can be found at https://admin.shopify.com/store/STORE_NAME/hydrogen/YOUR_ID.
If you installed the Headless channel it can be found at https://admin.shopify.com/store/STORE_NAME/headless_storefronts/YOUR_ID.

PUBLIC_CUSTOMER_ACCOUNT_API_CLIENT_ID

A token prefixed with shp_ that represents a client secret used in all authentication requests. The PUBLIC_CUSTOMER_ACCOUNT_API_CLIENT_ID can be found in Customer Account API settings page > Customer Account API Credentials

PUBLIC_CUSTOMER_ACCOUNT_API_URL

The target URI origin of authentication requests. For example: https://shopify.com/<your-shopify-store-id>. The PUBLIC_CUSTOMER_ACCOUNT_API_URL can be found in Customer Account API settings page > Application endpoints The URI is the common base URL of all the endpoints listed in the card.

SHOP_ID

The SHOP_ID can be found at https://admin.shopify.com/store/STORE_NAME/shop.json.

PUBLIC_SANITY_STUDIO_PROJECT_ID

The PUBLIC_SANITY_STUDIO_PROJECT_ID variable will be used to connect to your Sanity project. You can find it in your Sanity project admin dashboard or in your .env.sanity file.

PUBLIC_SANITY_STUDIO_DATASET

The PUBLIC_SANITY_STUDIO_DATASET variable will be used to connect to your Sanity project. You can find it in your Sanity project admin dashboard or in your .env.sanity file.

SANITY_STUDIO_USE_PREVIEW_MODE

Used by the Hydrogen app to enable/disable Sanity Preview Mode.

Your visitors won’t see these encodings, but the Overlays will see them and overlay the editing UI on hover.

More info about Sanity Loaders and Overlays.

SANITY_STUDIO_TOKEN

A viewer token is required for server-side fetching of draft content as well as “stega encoding” for Visual Editing.

Step 6: Countries, Currencies and Internationalization

Update the countries/index.ts file to add or update countries, currencies and languages. The default country will be used as a fallback when no country is found in the url. This file is shared across your Hydrogen app and Sanity studio.

export const countries: Localizations = {
default: {
  country: 'US',
  currency: 'USD',
  isoCode: 'en-us',
  label: 'United States (USD $)',
  language: 'EN',
  languageLabel: 'English',
},
'/fr': {
  country: 'FR',
  currency: 'EUR',
  isoCode: 'fr-fr',
  label: 'France (EUR €)',
  language: 'FR',
  languageLabel: 'French',
}
};

Under the hood, Fluid fetches countries, currencies and languages from Shopify. You can manage your Markets from the Shopify admin to add new currencies for example, learn more about Shopify Markets. Every content from Shopify is translatable from the Shopify admin. You can install and use Shopify’s free and official Translate and Adapt app.

Step 7: Set up the Customer Account

Update the application setup

For the Customer Account API to recognize your domain as a valid authentication host, edit your Customer Account API settings.

Under Application setup, click Edit ✎ to edit the endpoints. Under Callback URI(s), click Add Callback URI, and add your production domain, with /account/authorize appended:

https://<your-production-domain>/account/authorize

This is the URI your application will redirect to to continue the OAuth process after a successful customer login.

Under JavaScript origin(s), click Add origin, and then add your production domain.

Under Logout URI, click Add Logout URI, and then add your production domain.

Please read the official Shopify guide for more information.

Step 8: Launch your app

Before launching your app, you’ll need to install the dependencies of your Hydrogen app:

pnpm

pnpm install

yarn

yarn install

npm

npm install

Create initial Sanity data

To create the initial Sanity data, run the following command in your terminal:

pnpm

pnpm run create:initial

yarn

yarn run create:initial

npm

npm run create:initial

This command will run the create:initial script that will create the initial Sanity documents and singletons.

Launch your app

To launch your app, run the following command in your terminal:

pnpm

pnpm run dev

yarn

yarn run dev

npm

npm run dev

This command will start the Hydrogen app in development mode.

Troubleshooting

Sanity login error

Error: --with-user-token specified, but no auth token could be found. Run `sanity login`

Run npx -y sanity@latest login to login to your Sanity account.