Nitrogen

Nitrogen is a Nuxt template inspired by Shopify's Hydrogen framework for headless commerce. This template is designed to empower Nuxt developers to build fast, scalable, and customizable storefronts that incorporate key features from Hydrogen's starter theme.

Important

This template now features a minimal Sanity integration on a separate sanity branch. This is meant to pair with the Nitrogen Sanity Studio template, which synchronizes content between a Sanity dataset and your Shopify storefront.

✨ Key Features

• 💪 Strongly typed
• 🛒 Cart functionality
• 🔒 User authentication, with password reset
• 👤 Full customer account functionality
• 🗂️ Collection pages, with pagination
• 🕹️ Collection filter and sort functionality
• 👕 Product pages, with metafields
• 🔍 Search functionality
• 🌐 Shop localization
• 📫 Klaviyo integration
• 🧠 Sanity integration
• 🎠 Embla Carousel
• 🎨 Tailwind v4
• 🔮 Codegen

📖 Documentation

Tip

Read through the docs to learn how to configure your Shopify store to work with Nitrogen!

Nitrogen documentation

💻 Development

To begin using Nitrogen, you'll need to add the following environment variables:

# Shopify
NUXT_SHOPIFY_STOREFRONT=https://your-shop-name.myshopify.com
NUXT_SHOPIFY_ACCESS_TOKEN=your_storefront_access_token
NUXT_SHOPIFY_API_VERSION=2025-01

# Klaviyo (optional)
NUXT_KLAVIYO_PUBLIC_API_KEY=your_public_api_key
NUXT_KLAVIYO_PRIVATE_API_KEY=your_private_api_key
NUXT_KLAVIYO_API_VERSION=2025-01-15

# Sanity (optional)
NUXT_SANITY_PROJECT_ID=your_project_id
NUXT_SANITY_DATASET=production
NUXT_SANITY_API_VERSION=2025-02-02
NUXT_SANITY_STUDIO_URL=http://your-site-domain.com
NUXT_SANITY_API_READ_TOKEN=your_api_read_token

Warning

It is strongly recommended that you use the 2024-07 Storefront API version or higher. If not, you will not have access to new API features found within this template (this will cause breaking changes).

Local Setup

1. Install dependencies using pnpm install
2. Generate your project types using pnpm codegen
3. Start the development server using pnpm dev

⚡ Basic Usage

Nitrogen provides a minimal GraphQL client that seamlessly integrates with Shopify's Storefront API. It uses a server-side proxy to handle API authentication and requests, while offering a typed interface for executing GraphQL operations.

Operations

This project includes pre-built operations for common Storefront API queries and mutations. Feel free to add or remove operations that fit your project needs.

Composable

To get GraphQL operations, use the useShopify composable:

const shopify = useShopify();

Operations can be referenced using this composable with dot notation:

// Shopify
const shopify = useShopify();

// With dot notation
await shopify.cart.addLines(cart.id, [ ... ])
await shopify.product.get({ handle: 'example-product' })

With useAsyncData

Perfect for reactive data fetching in pages or components:

// Shopify
const shopify = useShopify();

// Fetch data
const productVars = computed<ProductQueryVariables>(() => ({
  handle: handle.value,
  country: shopStore.buyerCountryCode,
  language: shopStore.buyerLanguageCode
}))

const { data: productData } = await useAsyncData(
  `product-${handle.value}`,
  () => shopify.product.get(productVars.value),
  { watch: [productVars] }
);

// Computed data
const product = computed(() => productData.value)

With Pinia

Ideal for working with actions in your Pinia stores:

// Shopify
const shopify = useShopify();

// Cart actions
actions: {
  async createCart(input?: CartInput, optionalParams?: CartOptionalInput) {
    try {
      const response = await shopify.cart.create({
        input: input,
        ...optionalParams
      });

      if (response?.userErrors?.length) {
        throw new Error(response?.userErrors[0]?.message);
      }

      this.cart = response?.cart;
    } catch (error: any) {
      console.error('Cannot create cart:', error.message);
      throw error;
    }
  },
  // More actions...
}

🌱 Contribute

Contributions are always welcome! If you’d like to help improve this project, here’s how you can get involved:

• Post an issue: Use the Issues tab to report bugs or request new features.
• Start a discussion: Share ideas or ask for help in the Discussions tab.
• Submit a pull request: If you’d like to contribute, fork the repository, make your changes, and submit a pull request for review.

I actively monitor this repository and will do my best to respond quickly. Whether it’s fixing a small typo or adding a new feature, every contribution helps!