Set up Blueprint for storefronts

Get started

Create a free Pack account and explore our Quick Start guide. Continue with the following guide or check out the README file in the Pack's Blueprint Theme Repository.

Requirements

• Node.js version 16.14.0 or newer

After cloning your project, begin by installing your node packages:

npm install

Using our CLI tool

To streamline the setup of your Blueprint Theme, we provide a command-line interface (CLI) tool that simplifies the process. This tool automates several steps, making it easier and faster to get your development environment ready. Here’s how to use it:

1. Cloning and Setting Up the Blueprint Theme: Open your terminal and run the following command:

   npx @pack/create-hydrogen@latest
   

   CopyCopied!

   This command does the following:

   • Clones the Blueprint Theme repository to your local machine.
   • Installs all the necessary node packages using npm install.
   • Prepares your development environment for immediate use.

2. Running Your Project Locally: Once the setup is complete, you can start your development server with:

   npm run dev
   

   CopyCopied!

   This command serves your project on http://localhost:3000, allowing you to view and test your site in a local development environment.

3. No Pack Account Required: If you don't have a Pack account yet, no worries! The CLI tool allows you to run the Blueprint Theme with default Shopify data. This means you can start exploring the capabilities of the Hydrogen framework and how it integrates with Shopify without any initial setup or configuration.

4. Next Steps: After exploring the Blueprint Theme project, you might want to customize it further by connecting it to your Shopify Hydrogen storefront. You can do this by setting up environment variables as described below.

Environment Variables

To run your application locally, you need a .env file at the root of your project. Automate the creation of a .env file by pulling variables directly from your Shopify Hydrogen storefront using the Hydrogen CLI. Execute the following command and adhere to its prompts.

npx shopify hydrogen env pull

Alternatively, manually create a .env file and copy the values from your Shopify Hydrogen storefront. Locate the variables by navigating to the Hydrogen storefront > Storefront Settings > Environments & Variables. The necessary variables include:

SESSION_SECRET="XXX"
PUBLIC_STOREFRONT_API_TOKEN="XXX"
PUBLIC_STORE_DOMAIN="XXX"
PACK_PUBLIC_TOKEN="XXX"
PACK_SECRET_TOKEN="XXX"
PACK_STOREFRONT_ID="XXX"

Building for Production

This command emulates the deployment process Shopify Oxygen uses when deploying your site live.

npm run build

Building for Local Development

This command initiates a server locally on your machine at http://localhost:3000.

npm run dev

Pack Customizer Content

Access Pack Customizer data using the pack object in the Hydrogen context. Consider this example:

export async function loader({params, context, request}: LoaderFunctionArgs) {
  const {handle} = params;
  const storeDomain = context.storefront.getShopifyDomain();

  const searchParams = new URL(request.url).searchParams;
  const selectedOptions: any = [];

  // Assign selected options from the query string
  searchParams.forEach((value, name) => {
    selectedOptions.push({name, value});
  });

  const {data} = await context.pack.query(PRODUCT_PAGE_QUERY, {
    variables: {handle},
  });

  const {product} = await context.storefront.query(PRODUCT_QUERY, {
    variables: {
      handle,
      selectedOptions,
    },
  });

  ...
}

The data object contains all the Pack Section Setting content from CMS Authors in the Customizer, defined per Section's Setting schema. The product object holds Shopify-specific data from the Storefront API.

Refer to Section Schema API.

Caching

Pack employs the same Caching Strategy as the Hydrogen framework. For an example, see app/lib/pack/create-pack-client.ts

NOTE: The lib/pack library will eventually be moved to its own NPM package by Pack.

export function createPackClient(options: CreatePackClientOptions): Pack {
  const {apiUrl, cache, waitUntil, preview, contentEnvironment} = options;
  const previewEnabled = !!preview?.session.get('enabled');
  const previewEnvironment = preview?.session.get('environment');

  return {
    preview,
    isPreviewModeEnabled: () => previewEnabled,
    async query<T = any>(
      query: string,
      {variables, cache: strategy = CacheLong()}: QueryOptions = {},
    ) {
      const queryHash = await hashQuery(query, variables);
      const withCache = createWithCache<QueryResponse<T>>({
        cache,
        waitUntil,
      });

      // Preview environment overrides the content environment set during client creation
      const environment =
        previewEnvironment || contentEnvironment || PRODUCTION_ENVIRONMENT;
      const fetchOptions = {
        apiUrl,
        query,
        variables,
        token: options.token,
        previewEnabled,
        contentEnvironment: environment,
      };

      // Cache is bypassed in preview mode
      if (previewEnabled) return packFetch<T>(fetchOptions);

      return withCache(queryHash, strategy, () => packFetch<T>(fetchOptions));
    },
  };
}

Data Layer

The Pack Blueprint Theme sends pageView and addToCart (coming soon) events to Shopify Analytics via the Hydrogen hook. For details, visit: https://shopify.dev/docs/api/hydrogen/2023-07/utilities/sendshopifyanalytics

To see how events are submitted, refer to the products route (app/routes/products.$handle.tsx):

export async function loader({params, context, request}: LoaderFunctionArgs) {
  ...

   if (!data.productPage) {
    throw new Response(null, {status: 404});
  }
  // Optionally set a default variant for a consistently "orderable" product
  const selectedVariant =
    product.selectedVariant ?? product?.variants?.nodes[0];



  const productAnalytics: ShopifyAnalyticsProduct = {
    productGid: product.id,
    variantGid: selectedVariant.id,
    name: product.title,
    variantName: selectedVariant.title,
    brand: product.vendor,
    price: selectedVariant.price.amount,
  };
  const analytics = {
    pageType: AnalyticsPageType.product,
    resourceId: product.id,
    products: [productAnalytics],
    totalValue: parseFloat(selectedVariant.price.amount),
  };

  return defer({
    product,
    productPage: data.productPage,
    selectedVariant,
    storeDomain,
    analytics,
  });
}

SEO and Meta Tags

You can find the meta settings such as the title and description in the app\lib\seo.server.ts file.

By default, the site title is appended to the end of the page title using a | separator. For example, if the page title is "About Us" and the site title is "My Store," the resulting title tag will be "About Us | My Store." You can modify this behavior for each resource by passing an optional affixSiteTitleToSeoTitle parameter to the getMeta() function. Setting affixSiteTitleToSeoTitle to false will prevent the site title from being appended to the page title.

The seoSiteTitle is derived from the Pack Admin under Settings -> Search Engine Optimization. If this field is empty, it pulls the site title directly from Shopify.

For the homepage (/), the logic in getMeta() treats it uniquely. By default, if the page handle is '/', it sets the title to the siteTitle. You can change this behavior by commenting out or adjusting the following code in the getMeta() function:

if (page?.handle === '/') {
  pageTitle = pageTitle === 'Homepage' ? siteTitle : pageTitle;
  title = siteTitle;
}

By commenting out this block, the homepage will use the SEO title specified in the page's SEO settings, which you can set by navigating to Pack Admin -> Pages -> Homepage -> SEO Settings.

The getMeta() function also manages the meta description and Open Graph image (media) for the page. It prioritizes the SEO description and image specified for the resource (such as a product or collection) and falls back to the site-wide SEO settings or Shopify's defaults if those are not available. The description is truncated to 155 characters to ensure it fits within search engine result snippets.

Additionally, the getMeta() function handles the robots meta tags (noIndex and noFollow) based on the page's SEO settings. If page.seo.noIndex or page.seo.noFollow are set to true, the corresponding robots meta tags will be added to the page. You customize these in the Pack Admin under Pages -> [Page] -> SEO Settings.