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:

Cloning and Setting Up the Blueprint Theme: Open your terminal and run the following command:
npx @pack/create-hydrogen@latest
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.
Running Your Project Locally: Once the setup is complete, you can start your development server with:
npm run dev
This command serves your project on http://localhost:3000, allowing you to view and test your site in a local development environment.
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.
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,
      });
    }