Skip to main content

JavaScript SDK

The WithWine JavaScript SDK is designed to simplify common tasks associated with interacting with the WithWine API. The SDK implements an Authorization Flow that allows your users to Register an account, login to their account and access data related to their account such as Club Memberships etc., as well as logging out of their account and ensuring sessions are properly cleaned up.

Out of the box the SDK comes with built in support for the following popular frameworks:

But you might not use any of these, so we also have documentation to get the SDK integrated in your own custom code if required.

The SDK is a Work in progress

The SDK is currently bare bones and is still being developed, as such new features will be added as needed. Currently the primary use case for the SDK is to streamline the Authorization Flow to help you get your app up and interacting with the API as quickly and painlessly as possible.

Getting Started​

The WithWine JavaScript SDK is an Node.js package, you can install it using your favourite package manager (Yarn, PNPM or NPM) as you would any other Node.js package.

Using Yarn
yarn add @withwine/sdk

Once installed in your project you will have access to several modules that can be used either in a selection of the most popular JavaScript/TypeScript frameworks available, or you can leverage these modules directly in your own custom code.

Configuration​

The WithWine SDK depends on two important Configuration sources:

  • Environment Variables (.env is the recommended format)
  • A withwine.config.json file at the root of your application

Environment Variables​

At a bare minimum you will require a single Environment Variable WW_CLIENT_SECRET. This variable contains your WithWine Client Secret, this is a key that will allow your app to Authenticate with the WithWine API. Without this key you will not be able to Authorize users with your app.

The WithWine SDK uses a configuration file in the root of your project named withwine.config.json, this configuration file will contain all of the variables required by the SDK that are specific to your application. This file contains variables for each Environment (i.e. local, staging and production). To allow the SDK to know which set of variables to use, you need to supply it the correct key depending on the environment you are in. You can set this in the WW_ENV Environment variable.

During local development you might find issues with SSL certificates, particularly if you are developing on http://localhost, to work around this you can use NODE_TLS_REJECT_UNAUTHORIZED=0. It's important however that this is only set in your local development Environment.

Ultimately your .env.local file might look something like this:

WW_ENV=local
WW_CLIENT_SECRET=************************************
NODE_TLS_REJECT_UNAUTHORIZED=0

While your production environment would look like this:

WW_ENV=production
WW_CLIENT_SECRET=************************************

withwine.config.json​

The withwine.config.json file needs to be placed in the root directory of your app, the SDK will attempt to load it from this location, if it's not found the SDK with throw an error. This config file contains settings for each environment, local, staging and production, your local/development Environment will need to use the same WithWine URL's as your staging environment.

Local development limitations

You may encounter issues during local development related to https and [Authorization flows]. See this Troubleshooting guide for details on how to set up your environment to prevent issues.

{
  "local": {
    "brandId": ***,
    "clientId": "***",
    "appBaseUrl": "https://stage.yourappurl.com/",
    "authBaseUrl": "https://account.stage.withwine.com/",
    "assetBaseUrl": "https://stage.s3-cdn.withwine.com/",
    "apiBaseUrl": "https://stage.withwine.com"
  },
  "staging": {
    "brandId": ***,
    "clientId": "***",
    "appBaseUrl": "https://stage.yourappurl.com/",
    "authBaseUrl": "https://account.stage.withwine.com/",
    "assetBaseUrl": "https://stage.s3-cdn.withwine.com/",
    "apiBaseUrl": "https://stage.withwine.com"
  },
  "production": {
    "brandId": ***,
    "clientId": "***",
    "appBaseUrl": "https://www.yourappurl.com/",
    "authBaseUrl": "https://account.withwine.com/",
    "assetBaseUrl": "https://stage.s3-cdn.withwine.com/",
    "apiBaseUrl": "https://secure.withwine.com/"
  },
  ...
}

SDK integrations​

Modern web frameworks like Next.js, Nuxt, Remix, Sveltekit, NestJS, Astro, Qwik and SolidJS offer numerous benefits over traditional codebases. These frameworks provide a standardized structure that makes it easier for developers to organize their code and collaborate with others. This helps reduce development time, increase code quality, and make it easier to maintain the application over time.

They offer a wide range of features out of the box, such as server-side rendering, automatic code splitting, and optimized performance. These features not only improve the user experience but also help to improve search engine optimization (SEO) and accessibility, which are essential components of modern web development.

They also tend to have large and active communities, providing developers with access to a wealth of resources, such as plugins, integrations, and documentation. This can help developers solve problems faster and stay up-to-date with the latest industry trends.

In addition they provide developers with the ability to use modern web technologies and programming languages, such as TypeScript, tRPC and GraphQL to name just a few. This can help developers create more scalable, maintainable, and efficient web applications, which can provide a better user experience and reduce the cost of development over time.

Overall, modern web frameworks offer numerous benefits over traditional codebases and can help developers create high-quality, scalable, and maintainable web applications more efficiently.

Next.js​

The WithWine JavaScript SDK comes with built in support for Next.js out-of-the-box. The SDK provides various Higher Order Functions (HOF) and React Hooks that allow you to seamlessly integrate the WithWine API into your Next.js web applications.

Get started with Next.js »

Nuxt​

The WithWine JavaScript SDK comes with built in support for Nuxt out-of-the-box. The SDK provides various Composables and Middleware that allow you to seamlessly integrate the WithWine API into your Nuxt web applications.

Get started with Nuxt »

WIP

We are working on support for additional frameworks and these will be documented as we progress. If you have a specific need to get building on a modern framework that is not documented please speak to your WithWine Account manager.