@makaira/storefront-shop-adapter-shopify

This shop adapter can be used to connect your shopify shop with your storefront. This adapter is developed based on the shopify storefront api.

Installation

yarn install @makaira/storefront-types @makaira/storefront-shop-adapter-shopify

or

npm install @makaira/storefront-types @makaira/storefront-shop-adapter-shopify

Adding to your project

Basic usage

import { StorefrontShopAdapterShopify } from '@makaira/storefront-shop-adapter-shopify'

const client = new StorefrontShopAdapterShopify({
  url: '<SHOPIFY-GRAPHQL-STOREFRONT-API-URL>',
  accessToken: '<SHOPIFY-GRAPHQL-STOREFRONT-API-ACCESS-TOKEN>',
})

Usage with @makaira/storefront-react

import { StorefrontShopAdapterShopify } from '@makaira/storefront-shop-adapter-shopify'
import { ShopProvider } from '@makaira/storefront-react'

const client = new StorefrontShopAdapterShopify({
  url: '<SHOPIFY-GRAPHQL-STOREFRONT-API-URL>',
  accessToken: '<SHOPIFY-GRAPHQL-STOREFRONT-API-ACCESS-TOKEN>',
})

function Index() {
  return (
    <ShopProvider client={shopClient}>
      <App />
    </ShopProvider>
  )
}

In addition if you are using typescript in your project and want to get the correct autosuggestion you have to create a new declaration file (e.g index.d.ts) with the following content:

import '@makaira/storefront-react'
import { StorefrontShopAdapterShopify } from '@makaira/storefront-shop-adapter-shopify'

declare module '@makaira/storefront-react' {
  interface StorefrontReactCustomClient {
    client: StorefrontShopAdapterShopify
  }
}

Additional constructor arguments

| Argument | Required/Optional | Description | Type | | -------- | ----------------- | ----------- | ---- |

| Argument | Required/Optional | Description | Type | | --------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | url | required | The graphql storefront api url to made requests again. | string | | accessToken | required | The graphql storefront api access token. This must have the following scopes: unauthenticated_write_checkouts, unauthenticated_read_checkouts,unauthenticated_read_product_listings, unauthenticated_read_customers, unauthenticated_write_customers | string | | storage | optional | A storage engine for persisting data. This is by default the LocalStorage that is working in SSR. On Server Side every read and write will not be performed but not creates an error. | MakairaStorage | | fragments | optional | An object to overwrite the used fragments to customize the the responsed raw data. See for more details here. | object | | - checkoutFragment | optional | Fragment for the shopify Checkout object | string | | - checkoutUserErrorFragment | optional | Fragment for the shopify CheckoutUserError object | string | | - customerFragment | optional | Fragment for the shopify Customer object | string | | - userErrorFragment | optional | Fragment for the shopify UserError object | string | | - customerUserErrorFragment | optional | Fragment for the shopify CustomerUserError object | string | | contextOptions | optional | An objective to override the context in which the checkout will be created. | object | | - country | optional | The country of the customer in which the checkout will be created. | CountryCode Shopify-Docs | | - language | optional | The language in which the checkout will be created. | string |

Feature map

| Feature | Available | | ---------------- | --------- | | cart | | | - addItem | ✅ | | - getCart | ✅ | | - removeItem | ✅ | | - updateItem | ✅ | | review | | | - getReviews | ❌ | | - createReview | ❌ | | user | | | - login | ✅ | | - logout | ✅ | | - signup | ✅ | | - getUser | ✅ | | - forgotPassword | ✅ | | - update | ✅ | | - activate | ✅ | | - updatePassword | ✅ | | - addressUpdate | ✅ | | wishlist | | | - getWishlist | ❌ | | - addItem | ❌ | | - removeItem | ❌ |

Additional input properties

Cart

getCart

No additional properties

addItem

No additional properties

removeItem

| Property | Required/Optional | Description | Type | | ----------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | lineItemIds | required | In Shopify it is not possible to remove a product by its variantId. Instead the lineItemId is required. In this case the product property is disabled and ignored. Use only the lineItemsId. These can be accessed through the raw property on getCart. | string[] |

updateItem

| Property | Required/Optional | Description | Type | | ---------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | | lineItemId | required | In Shopify it is not possible to update a product in the shopping cart only by its variantId. Instead both IDs are required. The lineItemId can be accessed through the raw property on getCart. | string |

Review

getReviews

Not implemented

createReview

Not implemented

User

getUser

No additional properties

login

No additional properties

logout

No additional properties

signup

No additional properties

forgotPassword

No additional properties

Wishlist

getWishlist

Not implemented

addItem

Not implemented

removeItem

Not implemented

Customize used Fragments

In graphql you get what your request. Our base implementation only requests the minium amount of data to get the unified data response collected.

When your storefront grows you need even more data. Therefore you can customize the underlying fragments.

In the following explanation is shown, how to set a custom fragment and what is the basic fragment that is required so the adapter won't crash.

You can then access the data through the returned raw data on each functionality method.

checkoutFragment

import { StorefrontShopAdapterShopify } from '@makaira/storefront-shop-adapter-shopify'

const minimumCheckoutFragment = `
    fragment CheckoutFragment on Checkout {
        id
        lineItems(first: 50) {
            edges {
                node {
                    id
                    title
                    quantity
                    variant {
                        priceV2 {
                            amount
                            currencyCode
                        }
                        product {
                            featuredImage {
                                url
                            }
                        }
                    }
                    customAttributes {
                        key
                        value
                    }
                }
            }
        }
        completedAt
        webUrl
    }
`

const client = new StorefrontShopAdapterShopify({
  url: '<SHOPIFY-GRAPHQL-STOREFRONT-API-URL>',
  accessToken: '<SHOPIFY-GRAPHQL-STOREFRONT-API-ACCESS-TOKEN>',
  fragments: {
    checkoutFragment: minimumCheckoutFragment,
  },
})

When using with typescript

When you use typescript it is also possible to get the raw data correctly typed. Therefore create a new declaration file (e.g index.d.ts) with the following content:

import '@makaira/storefront-shop-adapter-shopify'

// You can set here the correct typescript definition of your custom fragment
type NewCheckoutFragment = {
  id: string
}

declare module '@makaira/storefront-shop-adapter-shopify' {
  interface StorefrontShopifyCustomFragments {
    checkoutFragment: NewCheckoutFragment
  }
}

checkoutUserErrorFragment

import { StorefrontShopAdapterShopify } from '@makaira/storefront-shop-adapter-shopify'

const minimumCheckoutUserErrorFragment = `
    fragment CheckoutUserErrorFragment on CheckoutUserError {
        field
        message
    }
`

const client = new StorefrontShopAdapterShopify({
  url: '<SHOPIFY-GRAPHQL-STOREFRONT-API-URL>',
  accessToken: '<SHOPIFY-GRAPHQL-STOREFRONT-API-ACCESS-TOKEN>',
  fragments: {
    checkoutUserErrorFragment: minimumCheckoutUserErrorFragment,
  },
})

When using with typescript

When you use typescript it is also possible to get the raw data correctly typed. Therefore create a new declaration file (e.g index.d.ts) with the following content:

import '@makaira/storefront-shop-adapter-shopify'

// You can set here the correct typescript definition of your custom fragment
type NewCheckoutUserErrorFragment = {
  field: string
}

declare module '@makaira/storefront-shop-adapter-shopify' {
  interface StorefrontShopifyCustomFragments {
    checkoutUserErrorFragment: NewCheckoutUserErrorFragment
  }
}

customerFragment

import { StorefrontShopAdapterShopify } from '@makaira/storefront-shop-adapter-shopify'

const minimumCustomerFragment = `
    fragment CustomerFragment on Customer {
        id
        firstName
        lastName
        email
    }
`

const client = new StorefrontShopAdapterShopify({
  url: '<SHOPIFY-GRAPHQL-STOREFRONT-API-URL>',
  accessToken: '<SHOPIFY-GRAPHQL-STOREFRONT-API-ACCESS-TOKEN>',
  fragments: {
    customerFragment: minimumCustomerFragment,
  },
})

When using with typescript

When you use typescript it is also possible to get the raw data correctly typed. Therefore create a new declaration file (e.g index.d.ts) with the following content:

import '@makaira/storefront-shop-adapter-shopify'

// You can set here the correct typescript definition of your custom fragment
type NewCustomerFragment = {
  id: string
}

declare module '@makaira/storefront-shop-adapter-shopify' {
  interface StorefrontShopifyCustomFragments {
    customerFragment: NewCustomerFragment
  }
}

userErrorFragment

import { StorefrontShopAdapterShopify } from '@makaira/storefront-shop-adapter-shopify'

const minimumUserErrorFragment = `
    fragment UserErrorFragment on UserError {
        field
        message
    }
`

const client = new StorefrontShopAdapterShopify({
  url: '<SHOPIFY-GRAPHQL-STOREFRONT-API-URL>',
  accessToken: '<SHOPIFY-GRAPHQL-STOREFRONT-API-ACCESS-TOKEN>',
  fragments: {
    userErrorFragment: minimumUserErrorFragment,
  },
})

When using with typescript

When you use typescript it is also possible to get the raw data correctly typed. Therefore create a new declaration file (e.g index.d.ts) with the following content:

import '@makaira/storefront-shop-adapter-shopify'

// You can set here the correct typescript definition of your custom fragment
type NewUserErrorFragment = {
  field: string
}

declare module '@makaira/storefront-shop-adapter-shopify' {
  interface StorefrontShopifyCustomFragments {
    userErrorFragment: NewUserErrorFragment
  }
}

customerUserErrorFragment

import { StorefrontShopAdapterShopify } from '@makaira/storefront-shop-adapter-shopify'

const minimumCustomerUserErrorFragment = `
    fragment CustomerUserErrorFragment on CustomerUserError {
        field
        message
    }
`

const client = new StorefrontShopAdapterShopify({
  url: '<SHOPIFY-GRAPHQL-STOREFRONT-API-URL>',
  accessToken: '<SHOPIFY-GRAPHQL-STOREFRONT-API-ACCESS-TOKEN>',
  fragments: {
    customerUserErrorFragment: minimumCustomerUserErrorFragment,
  },
})

When using with typescript

When you use typescript it is also possible to get the raw data correctly typed. Therefore create a new declaration file (e.g index.d.ts) with the following content:

import '@makaira/storefront-shop-adapter-shopify'

// You can set here the correct typescript definition of your custom fragment
type NewCustomerUserErrorFragment = {
  field: string
}

declare module '@makaira/storefront-shop-adapter-shopify' {
  interface StorefrontShopifyCustomFragments {
    customerUserErrorFragment: NewCustomerUserErrorFragment
  }
}

Update language and country of checkout

The StorefrontShopAdapterShopify exposes for changing the country and language of a checkout this method

setContextOptions({
  input: {
    options: { country: '', language: '' },
    lineItems: [],
  },
})

When this method is called a new checkout will the provided options will be created. Additionally, the options are stored in the localStorage so that after a reload of the page the options are still available.

You can also provide the lineItems to be added to the new checkout so that they won't get lost.

Example: Updating the checkout to use english as language and Great Britain as country whilst the checkout items survive.

const { client } = useShopClient()
const { cart } = useShopCart()

function updateContext() {
  client.setContextOptions({
    input: {
      options: {
        country: 'GB',
        language: 'EN',
      },
      lineItems: cart.items,
    },
  })
}

The correct country codes can be found at the Shopify Documentation The same applies to the language codes