Note
This repository is no longer used for active development. Please make future PRs in the new js-sdk-turbo repository. We will continue to fix bugs and security vulnerabilities in this repository until this version of the SDK has been sunsetted.
Stytch Javascript SDK
Dependencies
The Stytch SDK uses Node v16>=. We recommend using nvm to manage your local node versions. We currently use NPM v8.
nvm install 16
Installation
Stytch's javascript SDK uses Typescript.
npm install
We also make use
of commit ignoring
for large code style changes. If you use git blame
locally, run the following:
git config --local blame.ignoreRevsFile .git-blame-ignore-revs
Layout and Packaging
The SDK is composed of several moving pieces. Our top-level export is window.Stytch
, an ES module that allows for easy
construction of the login screen. The login screen itself is
a web component - a reusable and framework-agnostic piece
of HTML, CSS, and JS that can be embedded anywhere.
In the future, we will support numerous web components - one for each type of UI element that can be dropped in to place.
Inside the web component is a React application which handles rendering of DOM elements, interacting with user input, etc. The React runtime is bundled with the component, so we can be dropped directly in to places that do not use React, or alongside different versions of React. We can run anywhere JS can run.
All of our backend APIs are protected with CORS. In order to access them, we proxy calls through an iframe. Today, the SDK doesn't touch much sensitive data, but that will change in the near future. We want to start storing Stytch cookies inside the iframe, and isolate them from the parent document. The iframe might, for example, not let a request be made for a specific projectId unless it is embedded on the expected parent page.
Code structure:
js-sdk/
├─ stytch/
├─ src - Top-level window.Stytch
├─ iframe - Content for the js.stytch.com iframe
├─ loginScreen - Content for the login screen react component
Development & Contributing
The SDK is an embeddable UI toolkit that wraps the Stytch APIs. It is composed of several parts:
- Stytch.js, an ES Module that becomes availale as
window.Stytch
inside customer applications - Fabric.js, the Iframe'd UI that Stytch.js loads dynamically
- web-backend - the SDK's Backend for Frontend server
This repository contains Stytch.js, Fabric.js, and multiple "runtimes" that they can be embedded in.
- Storybook - a demo site that allows customers to explore the SDK confiugration options
- ./demo_app - A lightweight demo app for SDK contributors to use to exercise the SDK's functionality
Because the SDK depends on so many moving parts, it is highly recommended to use Remote Dev for all development needs.
The remote development script should automatically pick up your namespace.
okteto up
npm start
Run local webpack dev server
Before starting the local dev server, you need to pick a Stytch environment to point it at. Be aware that due to CORS headers, sending emails will not work properly when connected to remote environments - you will have to run an instance of Web Backend and an instance of API locally to achieve full functionality. Using Remote Dev is recommended instead.
npm run start-server
open http://localhost:8083
Testing
npm test
Linting
npm run lint # to check style
npm run lint-fix # to modify in place
Deploying
- Copy latest commit SHA from main: https://github.com/stytchauth/js-sdk/commits/main
- Go to the
Deploy
Github action: https://github.com/stytchauth/js-sdk/actions?query=workflow%3ADeploy - Click the
Run workflow
dropdown and enter the commit SHA and environment (prod
orstage
). Click theRun workflow
confirmation button.
@stytch/stytch-js and Client Libraries
Our public type definitions live inside the stytch-js repository. Any changes to our public definitions require us to release a new version of stytch-js and all libraries that depend on it.
Client libraries:
- stytch-react
- More to come!