@makaira/storefront-shop-adapter-shopify
TypeScript icon, indicating that this package has built-in type declarations

1.4.1 • Public • Published

@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

Package Sidebar

Install

npm i @makaira/storefront-shop-adapter-shopify

Weekly Downloads

44

Version

1.4.1

License

ISC

Unpacked Size

195 kB

Total Files

44

Last publish

Collaborators

  • cyklan
  • makaira-npm
  • avantic