WorkOS Widgets

A suite of React components providing functionality for enterprise app workflows.

Read the documentation

Local Development Setup

Install dependencies

Run pnpm install in the root directory to install the dependencies.

Run an example app

The following instructions will follow using the nextjs example but the same steps can be applied to other examples.

1. Spin up your local WorkOS instance (rush start).

2. Create a .env file in the root of the nextjs directory using the .env.example file as a reference.

3. Uncomment the values under # Optional configuration.

   # Optional configuration
   WORKOS_API_HOSTNAME="localhost"
   WORKOS_API_HTTPS=false
   WORKOS_API_PORT=7000

4. On your local WorkOS dashboard, go to the Get started homepage grab the WORKOS_API_KEY and WORKOS_CLIENT_ID and add them to your .env file.

5. Generate a 32 character password for WORKOS_COOKIE_PASSWORD and add it to your .env file.

   After steps 4 and 5, your .env file should look like this:

   # https://workos.com/docs/reference/api-keys
   WORKOS_API_KEY="sk_dev"                                               # retrieved from the WorkOS dashboard
   WORKOS_CLIENT_ID="client_dev"                                         # retrieved from the WorkOS dashboard
   WORKOS_COOKIE_PASSWORD="some-password-thats-32-chars-long"            # generate a 32 character password
   NEXT_PUBLIC_WORKOS_REDIRECT_URI="http://localhost:4040/auth/callback" # configured in the WorkOS dashboard

6. On your local WorkOS dashboard, go to the Redirects page and add the following URL to the Sign-in callback section:

   http://localhost:4040/auth/callback

7. On your local WorkOS dashboard, go to the Roles page and verify that the following exists, otherwise create it:

   Permissions

   Name: Manage users, Slug: widgets:users-table:manage

   Roles

   Name: Admin, Slug: admin, Permissions: widgets:users-table:manage

8. On your local WorkOS dashboard, go to the Organizations page, add yourself as a user to an organization. Then in the Users table of the organization, open the ... menu, open the Edit role, and set the role to Admin.

9. On your local WorkOS dashboard, go to the Authentication page and add the following URL to the Cross-Origin Resource Sharing (CORS) section:

   http://localhost:4040

10. Navigate to the packages/hosted-authkit directory and run rushx start to start the hosted AuthKit service.

11. Run pnpm dev --filter=nextjs to start the example app.

12. Navigate to http://localhost:4040/ and authenticate using Google to sign into your account.