npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@saleor/sdk

v0.7.0

Published

Saleor TS SDK

Downloads

3,627

Readme

This package contains methods providing Saleor business logic for a storefront and apps. It handles Saleor GraphQL queries and mutations, manages Apollo cache, and provides an internal state to manage popular storefront use cases, like user authentication.

:warning: Note: Saleor SDK is DEPRECATED. See the announcement.

For authentication, follow the Saleor docs and use @saleor/auth-sdk.

Table of Contents

Setup

There are two ways to use SDK - making custom implementation or using React components and hooks, which already has that implementation ready.

Using React

First install following dependencies to your project

npm install @saleor/sdk @apollo/client graphql

Use SaleorProvider with passed Saleor's client created by createSaleorClient in a prop. Then use React hooks in any component passed as child to SaleorProvider.

import {
  SaleorProvider,
  createSaleorClient,
  useAuth,
  useAuthState,
} from "@saleor/sdk";

const client = createSaleorClient({
  apiUrl: "<SALEOR_GRAPHQL_URL>",
  channel: "<CHANNEL>",
});

const rootElement = document.getElementById("root");
ReactDOM.render(
  <SaleorProvider client={client}>
    <App />
  </SaleorProvider>,
  rootElement
);

const App = () => {
  const { login } = useAuth();
  const { authenticated, user } = useAuthState();

  const handleSignIn = async () => {
    const { data } = await login({
      email: "[email protected]",
      password: "admin",
    });

    if (data.tokenCreate.errors.length > 0) {
      /**
       * Unable to sign in.
       **/
    } else if (data) {
      /**
       * User signed in successfully.
       **/
    }
  };

  if (authenticated && user) {
    return <span>Signed in as {user.firstName}</span>;
  }

  return <button onClick={handleSignIn}>Sign in</button>;
};

Using with NodeJS and other frameworks

npm install @saleor/sdk @apollo/client graphql

Then use createSaleorClient to get Saleor api methods and internal config variables like channel and Apollo client.

import { createSaleorClient } from "@saleor/sdk";

const client = createSaleorClient({
  apiUrl: "<SALEOR_GRAPHQL_URL>",
  channel: "<CHANNEL>",
});

const { auth, config, _internal } = client;

Finally, API methods can be used:

const { data } = await auth.login({
  email: "[email protected]",
  password: "admin",
});

if (data.tokenCreate.errors.length > 0) {
  /**
   * Unable to sign in.
   **/
} else if (data) {
  /**
   * User signed in successfully.
   **/
  const userData = api.auth.tokenCreate.user;
}

Custom HTTP communication with SDK authorization

SDK provides fetch method with all the necessary authorization headers assigned to HTTP requests and handled authorization token creation, verification and refresh inside, which you may use instead of built-in browser fetch. Using SDK auth login or logout methods will appropriately alter fetch behavior automatically, like including Authorization Bearer header in HTTP request.

import { createFetch } from "@saleor/sdk";

const authorizedFetch = createFetch();

const result = await authorizedFetch("https://example.com");

If you use GraphQL you may pass SDK fetch to the Apollo client:

const authorizationLink = new HttpLink({
  fetch: authorizedFetch,
});
const apolloClient = new ApolloClient({
  link: authorizationLink,
});

SDK fetch method uses cross-fetch under the hood.

Features

We provide an API with methods and fields, performing one, scoped type of work. You may access them straight from createSaleorClient() or use React hooks:

| API object | React hook | Description | | :----------- | :------------------ | :----------------------------------------------------------------------- | | getState() | useAuthState() | Returns current SDK state: user, authenticated and authenticating. | | auth | useAuth() | Handles user authentication methods. | | user | useUser() | Handles user account methods. | | config | useSaleorConfig() | Handles SDK configuration. |

SDK supports OpenId Connect methods provided by Saleor API. They are under auth object and useAuth hook. For more usage details, please check https://docs.saleor.io/docs/3.0/developer/available-plugins/openid-connect.

Local development

Our aim it to build SDK, highly configurable, as a separate package, which you will not require modifications. Although if you want to alter the project, especially if you want to contribute, it is possible to develop storefront and SDK simultaneously. To do this, you need to link it to the storefront's project.

$ cd lib
$ npm link
$ cd <your storefront path>
$ npm link @saleor/sdk

Notice that in our example storefront webpack is configured to always resolve react to ./node_modules/react. It may seem redundant for the most use cases, but helps in sdk's local development, because it overcomes npm's limitations regarding peer dependencies hoisting, explicitly telling webpack to always have one and only copy of react.

Configuration

Set environment variables:

export API_URI=https://your.saleor.instance.com/graphql/
export [email protected]
export TEST_AUTH_PASSWORD=admin

Development

  1. Download repository
  2. Install dependencies: npm i
  3. Now you can start files watcher with: npm run start

Production build

npm run build

Tests

Tests are located at /test directory. To start the test suite:

npm run test

All communication with API is prerecorded using Polly.JS. Unless requests changed or code executes new ones, no requests to API will be made.

Changes in /recordings directory should be reviewed before committing to make sure that changes in communication are intentional.

Code quality

The project has configured Prettier and ESLint. To check your code:

npm run lint

Fetch current GraphQL schema

npm run download-schema

Command will overwrite introspection.json with server schema, based on API_URL variable.

Updating TS types

GraphQL Code Generator is an automatic tool that converts schema to TS types. After changing schema file run:

npm run build-types

Updating recordings

Changes in the core user methods and tests may result in failing tests. Typically you may encounter the following error:

request to http://localhost:8000/graphql/ failed, reason: connect ECONNREFUSED 127.0.0.1:8000

To fix this run npm run test with the following variables:

  • API_URI
  • TEST_AUTH_EMAIL
  • TEST_AUTH_PASSWORD

After the tests run the recordings should be updated. Next time you run tests without variables, tests will use updated recordings.