Seam Components may be used in any web application as native ⚡Web Components ⚡
Seam Components are a set of white-labeled UI elements that can be added to your application in seconds. With these components, you can offer advanced device management features to your users without needing to develop complex logic for managing device state, refreshing data, and performing actions.
- Seam Components Overview
- Get started with Seam.
- Get started without needing a backend.
- Get started with Angular.
- Get started with Vue.
- Get started with Client Sessions.
- Make a Supported Devices Page.
- Reference the Component API.
- Find developer specific technical documentation in the README.
- Play with the components live in the interactive Storybook!
- See how the components work with a real Seam sandbox workspace in this live example app.
- Clone a sample app in your preferred framework.
- API reference documentation generated by TypeDoc.
Add this as a dependency to your project using npm with
$ npm install @seamapi/react
Check out the basic example app!
- Obtain a publishable key from the Seam Console.
- Wrap your React app with the
SeamProvider. - Drop in Seam Components.
import { ConnectAccountButton, DeviceTable, SeamProvider } from '@seamapi/react'
export function App() {
return (
<SeamProvider publishableKey='your_publishable_key'>
<main>
<h1>My App</h1>
<ConnectAccountButton />
<DeviceTable />
</main>
</SeamProvider>
)
}Check out the web component example app!
- Obtain a publishable key from the Seam Console.
- Add the
<script>tag to your page and drop in Seam Components.
<body>
<seam-connect-account-button
publishable-key="your_publishable_key"
></seam-connect-account-button>
<seam-device-table publishable-key="your_publishable_key"></seam-device-table>
<script
type="module"
src="https://react.seam.co/v/1.55.0/dist/elements.js"
></script>
</body>Update the version in the script tag above with the exact version of this package you would like to use.
All components interact with the Seam API via a set of React Hooks. You can use these hooks directly in your application to build your own components.
Import hooks directly from @seamapi/react or @seamapi/react/hooks.
For most applications, these imports are equivalent,
however if you are only using the hooks, we recommend importing from @seamapi/react/hooks
as it may enable performance or bundling improvements depending on your build system.
Hooks must be used inside the SeamProvider.
They are well-typed and follow a uniform API.
import { SeamProvider, useDevices } from '@seamapi/react/hooks'
export function App() {
return (
<SeamProvider publishableKey='your_publishable_key'>
<main>
<h1>My App</h1>
<Devices />
</main>
</SeamProvider>
)
}
function Devices() {
const { devices, isLoading, isError, error } = useDevices()
if (isLoading) {
return <p>Loading</p>
}
if (isError) {
return <p>{error?.message}</p>
}
return (
<>
<h2>Devices</h2>
<div>
{devices?.map((device) => (
<p key={device.device_id}>{device.properties.name}</p>
))}
</div>
</>
)
}CSS is automatically included unless using
<SeamProvider disableCssInjection />.
Components are styled with plain Cascading Style Sheets (CSS).
All styles are prefixed with seam- to avoid name collisions.
By default, the SeamProvider will inject a link tag into the document head to load the CSS.
If you prefer to manually load the CSS,
this behavior may be disabled with the disableCssInjection prop.
Then, either import the CSS using a supported bundler with
import '@seamapi/react/index.css'or place the following in the <head> tag:
You must match the version string below with the exact version of this package used by your application.
<link
rel="stylesheet"
href="https://react.seam.co/v/1.16.0/dist/index.min.css"
/>The
seam-prefixed CSS class names are not part of the stable API and may change unexpectedly.
Each component accepts a className prop.
The class name will be set on the top level container, or if a sub-component is rendered, passed though.
This makes them compatible with native CSS and most CSS-in-JS systems, e.g., Emotion and styled-components.
Fonts are automatically included unless using
<SeamProvider disableFontInjection />.
The components are optimized for use with Source Sans Pro, but will fallback to other system sans-serif fonts.
By default, the SeamProvider will inject a link tag into the document head to load the font.
If you prefer to manually provide the font,
this behavior may be disabled with the disableFontInjection prop.
Then, load it from Google Fonts by placing the following in the <head> tag:
<link
rel="stylesheet"
href="https://fonts.googleapis.com/css2?family=Source+Sans+Pro:wght@400;600;700&display=swap"
/>When using the default provider settings, the components are compatible with this CSP:
default-src 'self'; connect-src 'self' https://connect.getseam.com; img-src 'self' https://connect.getseam.com https://seam.co https://www.seam.co; font-src 'self' https://fonts.gstatic.com; style-src 'self' https://fonts.googleapis.com
Depending on which assets you choose to host yourself, the CSP may be made stricter.
By self hosting the styles and recommended fonts (or choosing not to use them), and proxying the Seam API endpoint, the components are compatible with this strict CSP:
default-src 'self'; img-src 'self' https://connect.getseam.com https://seam.co https://www.seam.co
The img-src is required as some components display device images from the Seam API.
When using the default endpoint, extend connect-src with
connect-src 'self' https://connect.getseam.com
When serving the fonts from Google Fonts, include font-src and style-src with
font-src 'self' https://fonts.gstatic.com; style-src 'self' https://fonts.googleapis.com
When serving the CSS styles from the default CDN, extend style-src with
style-src https://react.seam.co
$ git clone https://github.com/seamapi/react.git
$ cd react
$ nvm install
$ npm install
$ npm start
Primary development tasks are defined under scripts in package.json
and available via npm run.
View them with
$ npm run
The source code is hosted on GitHub. Clone the project with
$ git clone git@github.com:seamapi/react.git
You will need Node.js with npm and a Node.js debugging client. Alternately, develop in the cloud with Codespaces.
Be sure that all commands run under the correct Node version, e.g., if using nvm, install the correct version with
$ nvm install
Set the active version for each shell session with
$ nvm use
Install the development dependencies with
$ npm install
Develop components with Storybook.
Run the full storybook in development mode with
$ npm start
The deployed storybook runs in docs mode which does not contain the full storybook. Develop the storybook in docs mode with
$ npm run docs:start
Chromatic automates visual and interaction tests for Storybook.
The full storybook for the main branch is hosted at storybook.react.seam.co.
On each commit, the full storybook is published to Chromatic for review. On pull requests, Chromatic will run UI regressions tests on each commit. Chromatic reports results as status checks that link directly to the storybook.
If changes are detected, follow the link in the status checks to approve the changes. Contributors must be granted access to approve changes on Chromatic; request access from another maintainer of this project.
Every pull request deploys the storybook in docs mode with the examples in a Vercel Preview Deployment where you may comment directly on the preview. This is the same storybook published on react.seam.co.
This project uses a fake version of Seam Connect to have deterministic responses for rendering views and running tests.
Edit the seed data for the fake or find relevant ids for testing components here:
Write tests with Jest.
Find fully working examples apps under examples/.
Each example app is built and deployed along with the Storybook documentation.
Run and develop the examples with,
$ npm run examples
The React components under src/lib/icons are generated from assets/icons.
To add a new icon:
- Place or update the SVG icon in
assets/icons. - Run
npm run generate. - Import with
import { SeamIcon } from 'lib/icons/SeamIcon.js'New versions are released automatically with semantic-release as long as commits follow the Angular Commit Message Conventions.
Publish a new version by triggering a version workflow_dispatch on GitHub Actions.
The version input will be passed as the first argument to npm-version.
This may be done on the web or using the GitHub CLI with
$ gh workflow run version.yml --raw-field version=<version>
GitHub Actions should already be configured: this section is for reference only.
The following repository secrets must be set on GitHub Actions:
NPM_TOKEN: npm token for installing and publishing packages.GH_TOKEN: A personal access token for the bot user withpackages:writeandcontents:writepermission.GIT_USER_NAME: The GitHub bot user's real name.GIT_USER_EMAIL: The GitHub bot user's email.GPG_PRIVATE_KEY: The GitHub bot user's GPG private key.GPG_PASSPHRASE: The GitHub bot user's GPG passphrase.VERCEL_ACCESS_TOKEN: The Vercel project token.
The following repository variables must be set on GitHub Actions:
VERCEL_TEAM_ID: The Vercel team id.STORYBOOK_SEAM_ENDPOINT: The Seam endpoint to use with Storybook.STORYBOOK_SEAM_PUBLISHABLE_KEY: The Seam publishable key to use with Storybook.STORYBOOK_SEAM_USER_IDENTIFIER_KEY: The Seam user identifer key to use with Storybook.
The following repository variables must be set on GitHub Actions:
CLOUDFLARE_ACCOUNT_ID: The Cloudflare account id.CLOUDFLARE_R2_BUCKET_NAME: The Cloudflare R2 bucket name.CLOUDFLARE_R2_BUCKET_REGION: The Cloudflare R2 bucket region.CLOUDFLARE_R2_ACCESS_KEY_ID: The Cloudflare R2 bucket access key id.
The following repository secrets must be set on GitHub Actions:
CLOUDFLARE_R2_SECRET_ACCESS_KEY: The Cloudflare R2 secret access key.
Vercel should already be configured: this section is for reference only.
The following environment variables must be set on Vercel:
SEAM_PUBLISHABLE_KEY: The Seam publishable key to use with the examples.SEAM_USER_IDENTIFIER_KEY: The Seam user identifer key to use with the examples..STORYBOOK_SEAM_PUBLISHABLE_KEY: The Seam publishable key to use with Storybook.STORYBOOK_SEAM_USER_IDENTIFIER_KEY: The Seam user identifer key to use with Storybook.
If using squash merge, edit and ensure the commit message follows the Angular Commit Message Conventions specification. Otherwise, each individual commit must follow the Angular Commit Message Conventions specification.
- Create your feature branch (
git checkout -b my-new-feature). - Make changes.
- Commit your changes (
git commit -am 'Add some feature'). - Push to the branch (
git push origin my-new-feature). - Create a new draft pull request.
- Ensure all checks pass.
- Mark your pull request ready for review.
- Wait for the required approval from the code owners.
- Merge when ready.
This npm package is licensed under the MIT license.
This software is provided by the copyright holders and contributors "as is" and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. In no event shall the copyright holder or contributors be liable for any direct, indirect, incidental, special, exemplary, or consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this software, even if advised of the possibility of such damage.