diff --git a/.changeset/five-fishes-joke.md b/.changeset/five-fishes-joke.md new file mode 100644 index 00000000000..ec65ebe608d --- /dev/null +++ b/.changeset/five-fishes-joke.md @@ -0,0 +1,22 @@ +--- +"@clerk/chrome-extension": patch +"@clerk/tanstack-start": patch +"@clerk/localizations": patch +"@clerk/clerk-js": patch +"@clerk/elements": patch +"@clerk/clerk-sdk-node": patch +"@clerk/backend": patch +"@clerk/express": patch +"@clerk/fastify": patch +"@clerk/testing": patch +"@clerk/upgrade": patch +"@clerk/nextjs": patch +"@clerk/themes": patch +"@clerk/astro": patch +"@clerk/clerk-react": patch +"@clerk/remix": patch +"@clerk/types": patch +"@clerk/clerk-expo": patch +--- + +Tidy up and improve README diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 5bd7e3aab1d..c0804109c12 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -79,7 +79,9 @@ To set up your development environment, please follow these steps: This ensures that all internal TypeScript types are generated and any dependencies between packages are resolving. -For package specific setup, refer to the `Build` section of the specific package (e.g. `packages//README.md#build`). +Once you're ready to make changes, run `npm run dev` from the monorepo root. + +If you want to run the `dev` script of an individual package, navigate to the folder and run the script from there. This way you can also individually run the `build` script. ### Documenting your changes diff --git a/packages/astro/README.md b/packages/astro/README.md index e5438ea978d..e1f3c817c4e 100644 --- a/packages/astro/README.md +++ b/packages/astro/README.md @@ -6,10 +6,9 @@
+

@clerk/astro

-# @clerk/astro -
[![Chat on Discord](https://img.shields.io/discord/856971667393609759.svg?logo=discord)](https://clerk.com/discord) @@ -22,155 +21,38 @@ · [Request a Feature](https://feedback.clerk.com/roadmap) · -[Ask a Question](https://github.com/clerk/javascript/discussions) +[Get help](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_astro)
---- - -## Overview - -Clerk is the easiest way to add authentication and user management to your Astro application. Add sign up, sign in, and profile management to your Astro application in minutes. - -## Getting Started +[Clerk](https://clerk.com/?utm_source=github&utm_medium=clerk_astro) is the easiest way to add authentication and user management to your Astro application. Add sign up, sign in, and profile management to your application in minutes. ### Prerequisites - Astro 3.2 or later - Node.js `>=18.17.0` or later +- An existing Clerk application. [Create your account for free](https://dashboard.clerk.com/sign-up?utm_source=github&utm_medium=clerk_astro). ### Installation -Add `@clerk/astro` as a dependency - -**With npm** - -```sh -npm install @clerk/astro -``` - -**With yarn** - -```sh -yarn add @clerk/astro -``` - -**With pnpm** - -```sh -pnpm add @clerk/astro -``` - -### Build - -To build the package locally with the TypeScript compiler, run: - -```sh -npm run build -``` - -To build the package in watch mode, run the following: +The fastest way to get started with Clerk is by following the [Astro Quickstart](https://clerk.com/docs/quickstarts/astro?utm_source=github&utm_medium=clerk_astro). -```sh -npm run dev -``` +You'll learn how to install `@clerk/astro`, set up your environment keys, add the `clerk()` integration to your application, use the Clerk middleware, and use Clerk's prebuilt components. ## Usage -### Set environment variables - -```sh -PUBLIC_CLERK_PUBLISHABLE_KEY=pk_(test|live)_xxxxxxx -CLERK_SECRET_KEY=sk_(test|live)_xxxxxxx - -PUBLIC_CLERK_SIGN_IN_URL=/sign-in # update this if sign in page exists on another path -PUBLIC_CLERK_SIGN_UP_URL=/sign-up # update this if sign up page exists on another path -``` - -### Update `env.d.ts` - -```ts -/// -/// -``` - -### Add integrations - -Follow [the instructions](https://clerk.com/docs/quickstarts/astro) in our documentation. - -Example configuration file - -```js -import { defineConfig } from 'astro/config'; -import node from '@astrojs/node'; -import clerk from '@clerk/astro'; - -export default defineConfig({ - integrations: [clerk()], - adapter: node({ mode: 'standalone' }), - output: 'server', -}); -``` - -### Add a middleware file - -This step is required in order to use SSR or any control component. Create a `middleware.ts` file inside the `src/` directory. - -```ts -import { clerkMiddleware } from '@clerk/astro/server'; - -export const onRequest = clerkMiddleware(); -``` - -### Use components inside .astro files - -```astro ---- -import { SignedIn, SignedOut, UserButton, SignInButton } from "@clerk/astro/components"; ---- - - - - - - - - - -
-

{title}

- -
-
- -
- - -``` - -_For further details and examples, please refer to -our [Documentation](https://clerk.com/docs?utm_source=github&utm_medium=clerk_nextjs)._ +For further information, guides, and examples visit the [Astro reference documentation](https://clerk.com/docs/references/astro/overview?utm_source=github&utm_medium=clerk_astro). ## Support You can get in touch with us in any of the following ways: - Join our official community [Discord server](https://clerk.com/discord) -- Create a [GitHub Discussion](https://github.com/clerk/javascript/discussions) -- Contact options listed on [our Support page](https://clerk.com/support?utm_source=github&utm_medium=clerk_astro) +- On [our support page](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_astro) ## Contributing -We're open to all community contributions! If you'd like to contribute in any way, please -read [our contribution guidelines](https://github.com/clerk/javascript/blob/main/docs/CONTRIBUTING.md)) -. +We're open to all community contributions! If you'd like to contribute in any way, please read [our contribution guidelines](https://github.com/clerk/javascript/blob/main/docs/CONTRIBUTING.md) and [code of conduct](https://github.com/clerk/javascript/blob/main/docs/CODE_OF_CONDUCT.md). ## Security @@ -178,8 +60,7 @@ read [our contribution guidelines](https://github.com/clerk/javascript/blob/main `@clerk/astro` is provided **"as is"** without any **warranty**. Use at your own risk. -_For more information and to report security issues, please refer to -our [security documentation](https://github.com/clerk/javascript/blob/main/docs/SECURITY.md)._ +_For more information and to report security issues, please refer to our [security documentation](https://github.com/clerk/javascript/blob/main/docs/SECURITY.md)._ ## License diff --git a/packages/backend/README.md b/packages/backend/README.md index 144b159789e..d21c0957deb 100644 --- a/packages/backend/README.md +++ b/packages/backend/README.md @@ -6,10 +6,9 @@
+

@clerk/backend

-# @clerk/backend -
[![Chat on Discord](https://img.shields.io/discord/856971667393609759.svg?logo=discord)](https://clerk.com/discord) @@ -22,187 +21,39 @@ · [Request a Feature](https://feedback.clerk.com/roadmap) · -[Ask a Question](https://github.com/clerk/javascript/discussions) +[Get help](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_backend)
---- - -## Overview - -This package provides Clerk Backend API resources and low-level authentication utilities for JavaScript environments. It is mostly used as the base for other Clerk SDKs but it can be also used on its own. - -### Features - -- Built for V8 isolates (Cloudflare Workers, Vercel Edge Runtime, etc...). -- Make it isomorphic to work across all modern JS runtimes. -- Use options injection for all keys and settings. -- Support multiple `CLERK_SECRET_KEY` for multiple instance REST access. -- Align JWT key resolution algorithm across all environments (Function param > Environment variable > JWKS from API). -- Tested automatically across different runtimes (Node, CF Workers, Vercel Edge middleware.) -- Refactor the Rest Client API to return `{data, errors}` instead of throwing errors. -- Export a generic verifyToken for Clerk JWTs verification. -- Align AuthData interface for SSR. -- Export CJS and ESM. - -## How to use - -Works on Node.js `>=18.17.0` (or later) or on any V8 Isolates runtimes (eg Cloudflare Workers). - -```sh -npm install @clerk/backend -``` - -``` -import { createClerkClient } from '@clerk/backend'; - -const clerk = createClerkClient({ secretKey: '...' }); - -await clerk.users.getUser("user_..."); -``` - -### API - -#### createClerkClient(options: ClerkOptions) - -Create Clerk SDK that includes an HTTP Rest client for the Backend API and session verification helpers. The clerk object contains the following APIs and methods: - -```js -import { createClerkClient } from '@clerk/backend'; - -const clerk = createClerkClient({ secretKey: '...' }); - -await clerk.users.getUser('user_...'); - -// Available APIs -clerk.allowlistIdentifiers; -clerk.clients; -clerk.emailAddresses; -clerk.emails; -clerk.invitations; -clerk.organizations; -clerk.phoneNumbers; -clerk.redirectUrls; -clerk.sessions; -clerk.signInTokens; -clerk.users; - -// These functions should be used by framework-specific libraries, such as @clerk/nextjs or @clerk/remix. - -// Compute the authentication state given the request parameters. -clerk.authenticateRequest(options); - -// Build debug payload of the request state. -clerk.debugRequestState(requestState); -``` - -#### verifyToken(token: string, options: VerifyTokenOptions) - -Verifies a Clerk generated JWT (i.e. Clerk Session JWT and Clerk JWT templates). The key resolution via JWKS or local values is handled automatically. - -```js -import { verifyToken } from '@clerk/backend'; - -const { result, error } = await verifyToken(token, { - issuer: '...', - authorizedParties: '...', -}); -``` - -#### verifyJwt(token: string, options: VerifyJwtOptions) - -Verifies a Clerk generated JWT (i.e. Clerk Session JWT and Clerk JWT templates). The key needs to be provided in the options. - -```js -import { verifyJwt } from '@clerk/backend/jwt'; - -const { result, error } = verifyJwt(token, { - key: JsonWebKey | string, - authorizedParties: '...', -}); -``` - -#### decodeJwt(token: string) - -Decodes a JWT. - -```js -import { decodeJwt } from '@clerk/backend/jwt'; - -const { result, error } = decodeJwt(token); -``` - -#### hasValidSignature(jwt: Jwt, key: JsonWebKey | string) - -Verifies that the JWT has a valid signature. The key needs to be provided. - -```js -import { hasValidSignature } from '@clerk/backend/jwt'; - -const { result, error } = await hasValidSignature(token, jwk); -``` - -#### debugRequestState(requestState) - -Generates a debug payload for the request state - -```js -import { debugRequestState } from '@clerk/backend/internal'; - -debugRequestState(requestState); -``` - -#### signedInAuthObject(sessionClaims, options) - -Builds the AuthObject when the user is signed in. - -```js -import { signedInAuthObject } from '@clerk/backend/internal'; - -signedInAuthObject(jwtPayload, options); -``` - -#### signedOutAuthObject() - -Builds the empty AuthObject when the user is signed out. - -```js -import { signedOutAuthObject } from '@clerk/backend/internal'; - -signedOutAuthObject(); -``` +## Getting Started -#### sanitizeAuthObject(authObject) +[Clerk's](https://clerk.com/?utm_source=github&utm_medium=clerk_backend) JavaScript Backend SDK exposes [Clerk's Backend API](https://clerk.com/docs/reference/backend-api) resources and low-level authentication utilities **for JavaScript environments**. -Removes sensitive private metadata from user and organization resources in the AuthObject +### Prerequisites -```js -import { sanitizeAuthObject } from '@clerk/backend/internal'; +- Node.js `>=18.17.0` (or later) or any V8 isolates runtime +- An existing Clerk application. [Create your account for free](https://dashboard.clerk.com/sign-up?utm_source=github&utm_medium=clerk_backend). -sanitizeAuthObject(authObject); -``` +### Installation -#### prunePrivateMetadata(obj) +The fastest way to get started with `@clerk/backend` is by following the [JavaScript Backend SDK reference documentation](https://clerk.com/docs/references/backend/overview?utm_source=github&utm_medium=clerk_backend). -Removes any `private_metadata` and `privateMetadata` attributes from the object to avoid leaking sensitive information to the browser during SSR. +You'll learn how to install `@clerk/backend` and how to use `createClerkClient()`. -```js -import { prunePrivateMetadata } from '@clerk/backend/internal'; +## Usage -prunePrivateMetadata(obj); -``` +For further information, guides, and examples visit the [JavaScript Backend SDK reference documentation](https://clerk.com/docs/references/backend/overview?utm_source=github&utm_medium=clerk_backend). It lists all the available APIs and methods. ## Support You can get in touch with us in any of the following ways: - Join our official community [Discord server](https://clerk.com/discord) -- Create a [GitHub Discussion](https://github.com/clerk/javascript/discussions) -- Contact options listed on [our Support page](https://clerk.com/support?utm_source=github&utm_medium=clerk_backend) +- On [our support page](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_backend) ## Contributing -We're open to all community contributions! If you'd like to contribute in any way, please read [our contribution guidelines](https://github.com/clerk/javascript/blob/main/docs/CONTRIBUTING.md). +We're open to all community contributions! If you'd like to contribute in any way, please read [our contribution guidelines](https://github.com/clerk/javascript/blob/main/docs/CONTRIBUTING.md) and [code of conduct](https://github.com/clerk/javascript/blob/main/docs/CODE_OF_CONDUCT.md). ## Security diff --git a/packages/backend/TODOs.md b/packages/backend/TODOs.md deleted file mode 100644 index 0761cc2a8e1..00000000000 --- a/packages/backend/TODOs.md +++ /dev/null @@ -1,24 +0,0 @@ -## Goals - -- [x] Build for V8 isolates first. -- [x] Make it isomorphic to work across all modern JS runtimes. -- [x] Use options injection for all keys and settings. -- [x] Support multiple CLERK_API_KEY for multiple instance REST access. -- [x] Align JWT key resolution algorithm across all environments (Function param > Environment variable > JWKS from API). -- [x] Tested automatically across different runtimes (Node, CF Workers, Vercel Edge middleware.) -- [x] Clean up Clerk interstitial logic. -- [x] Refactor the Rest Client API to return `{data, errors}` instead of throwing errors. -- [x] Export a generic verifyToken for Clerk JWTs verification. -- [x] Align AuthData interface for SSR. -- [x] Export CJS and ESM. - -## Remaining tasks - -- [] Build test coverage -- [] Run suite in Deno runtime -- [] Custom claim validation in verifyToken for JWT templates -- [] Replace QUnit with Mocha in a browser-like setup using ESM. -- [] Replace Sinon with https://mswjs.io -- [] Add tribute to https://github.com/cfworker/cfworker/tree/main/packages/jwt -- [] Make test suite files load dynamically so that we don't need to manually update `suites.ts` every time we add a new test file. -- [] Dynamic resource parsing to remove the deserializer diff --git a/packages/chrome-extension/README.md b/packages/chrome-extension/README.md index 3f45069a20f..c644c68d372 100644 --- a/packages/chrome-extension/README.md +++ b/packages/chrome-extension/README.md @@ -6,10 +6,9 @@
+

@clerk/chrome-extension

-# @clerk/chrome-extension -
[![Chat on Discord](https://img.shields.io/discord/856971667393609759.svg?logo=discord)](https://clerk.com/discord) @@ -22,131 +21,116 @@ · [Request a Feature](https://feedback.clerk.com/roadmap) · -[Ask a Question](https://github.com/clerk/javascript/discussions) +[Get help](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_chrome_extension)
---- - -## Overview - -[Clerk](https://clerk.com?utm_source=github&utm_medium=clerk_chrome_extension) is the easiest way to add authentication and user management to your chrome extension. To gain a better understanding of the Clerk React SDK and [Frontend API](https://reference.clerk.com/reference/frontend-api-reference), refer to -the Node SDK and Backend API documentation. - ## Getting Started -To use this package you should first create a Clerk application and retrieve a `Publishable Key` for you application to be used as environment variables `VITE_CLERK_PUBLISHABLE_KEY`. +[Clerk](https://clerk.com/?utm_source=github&utm_medium=clerk_chrome_extension) is the easiest way to add authentication and user management to your Chrome Extension. Add sign up, sign in, and profile management to your application in minutes. ### Prerequisites - Node.js `>=18.17.0` or later +- An existing Clerk application. [Create your account for free](https://dashboard.clerk.com/sign-up?utm_source=github&utm_medium=clerk_chrome_extension). +- An existing React app (using [Vite](https://crxjs.dev/vite-plugin/) for example) ### Installation -```shell -npm install @clerk/chrome-extension -``` +1. Add `@clerk/chrome-extension` to your project: + + ```shell + npm install @clerk/chrome-extension + ``` + +1. Retrieve the **Publishable key** from your [Clerk dashboard](https://dashboard.clerk.com/last-active?path=api-keys) and set it as an environment variable. For example, if you used Vite: + + ```sh + VITE_CLERK_PUBLISHABLE_KEY=pk_test_xxx + ``` + +1. Add `` to your app and define the `routerPush` & `routerReplace` properties. For example, with using `react-router-dom`: + + ```tsx + // App.tsx + import { SignedIn, SignedOut, SignIn, SignUp, ClerkProvider } from '@clerk/chrome-extension'; + import { useNavigate, Routes, Route, MemoryRouter } from 'react-router-dom'; + + function HelloUser() { + return

Hello user

; + } + + const publishableKey = process.env.VITE_CLERK_PUBLISHABLE_KEY || ''; + + function ClerkProviderWithRoutes() { + const navigate = useNavigate(); + + return ( + navigate(to)} + routerReplace={to => navigate(to, { replace: true })} + > + + } + /> + + + + + + + + + } + /> + + + ); + } + + function App() { + return ( + + + + ); + } + + export default App; + ``` ## Usage -Standalone usage snippet: - -```tsx -// App.tsx -import { SignedIn, SignedOut, SignIn, SignUp, ClerkProvider } from '@clerk/chrome-extension'; -import { useNavigate, Routes, Route, MemoryRouter } from 'react-router-dom'; - -function HelloUser() { - return

Hello user

; -} - -const publishableKey = process.env.VITE_CLERK_PUBLISHABLE_KEY || ''; - -function ClerkProviderWithRoutes() { - const navigate = useNavigate(); - - return ( - navigate(to)} - routerReplace={to => navigate(to, { replace: true })} - > - - } - /> - - - - - - - - - } - /> - - - ); -} - -function App() { - return ( - - - - ); -} - -export default App; -``` - -WebSSO usage snippet: - -```tsx -// App.tsx -// use same code with the above & add the syncSessionWithTab prop in - -// ... - navigate(to)} - routerReplace={to => navigate(to, { replace: true })} - syncSessionWithTab -> - {/* ... */} - -// ... -``` - -Examples of a chrome extension using the `@clerk/chrome-extension` package for authentication -can be found in our `clerk-chrome-extension-starter` github repository. -The 2 supported cases (links to different branches of the same repository): +Example repositories: - [Standalone](https://github.com/clerk/clerk-chrome-extension-starter/tree/main): The extension is using its own authentication - [WebSSO](https://github.com/clerk/clerk-chrome-extension-starter/tree/webapp_sso): The extensions shares authentication with a website in the same browser -## WebSSO required settings +### WebSSO -### Extension Manifest (`manifest.json`) +If you want to use **WebSSO** (extension shares authentication state with a website in same browser) you'll need to add the `syncSessionWithTab` prop to ``. -#### Permissions +#### Extension Manifest (`manifest.json`) You must enable the following permissions in your `manifest.json` file: -``` -"permissions": ["cookies", "storage"] +```json +{ + "permissions": ["cookies", "storage"] +} ``` -- For more info on the "cookies" permission: (Google Developer Cookies Reference)[https://developer.chrome.com/docs/extensions/reference/cookies/] -- For more info on the "storage" permission: (Google Developer Storage Reference)[https://developer.chrome.com/docs/extensions/reference/storage/] +More info on the "cookies" permission: [Google Developer Cookies Reference](https://developer.chrome.com/docs/extensions/reference/cookies/). +More info on the "storage" permission: [Google Developer Storage Reference](https://developer.chrome.com/docs/extensions/reference/storage/). #### Host Permissions @@ -155,15 +139,13 @@ You must enable the following host permissions in your `manifest.json` file: - **Development:** `"host_permissions": ["http://localhost"]` - If you're using a domain other than `localhost`, you'll want replace that entry with your domain: `http://` - **Production:** `"host_permissions": ["https:///"]` - - Your Frontend API URL can be found in `Clerk Dashboard > API Keys > Advanced > Clerk API URLs`. - -For more info on host permissions: (Google Developer `host_permissions` Reference)[https://developer.chrome.com/docs/extensions/mv3/declare_permissions/#host-permissions] + - Your Frontend API URL can be found in [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=api-keys) under the **Show API URLs** option. - +For more info on host permissions visit [Google's developer `host_permissions` reference](https://developer.chrome.com/docs/extensions/mv3/declare_permissions/#host-permissions). -### Clerk Settings +#### Clerk Settings -Add your Chrome extension origin to your instance allowed_origins using BAPI: +Add your Chrome extension origin to your instance's `allowed_origins` using the [Backend API](https://clerk.com/docs/reference/backend-api): ```bash curl -X PATCH https://api.clerk.com/v1/instance \ @@ -172,27 +154,18 @@ curl -X PATCH https://api.clerk.com/v1/instance \ -d '{"allowed_origins": ["chrome-extension://extension_id_goes_here"]}' ``` -## Deploy to Production - -Setting the `allowed_origins` (check [Clerk Settings](#clerk-settings)) is **REQUIRED** for both **Development** and **Production** instances when using the WebSSO use case. - -## Learn More - -You can learn more in the [Create React App documentation](https://facebook.github.io/create-react-app/docs/getting-started). - -To learn React, check out the [React documentation](https://reactjs.org/). +Setting the `allowed_origins` is **required** for both **Development** and **Production** instances. ## Support You can get in touch with us in any of the following ways: - Join our official community [Discord server](https://clerk.com/discord) -- Create a [GitHub Discussion](https://github.com/clerk/javascript/discussions) -- Contact options listed on [our Support page](https://clerk.com/support?utm_source=github&utm_medium=clerk_chrome_extension) +- On [our support page](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_chrome_extension) ## Contributing -We're open to all community contributions! If you'd like to contribute in any way, please read [our contribution guidelines](https://github.com/clerk/javascript/blob/main/docs/CONTRIBUTING.md). +We're open to all community contributions! If you'd like to contribute in any way, please read [our contribution guidelines](https://github.com/clerk/javascript/blob/main/docs/CONTRIBUTING.md) and [code of conduct](https://github.com/clerk/javascript/blob/main/docs/CODE_OF_CONDUCT.md). ## Security diff --git a/packages/clerk-js/README.md b/packages/clerk-js/README.md index fa8dc7fb2d1..c8f03d9c9a5 100644 --- a/packages/clerk-js/README.md +++ b/packages/clerk-js/README.md @@ -6,10 +6,9 @@
+

@clerk/clerk-js

-# @clerk/clerk-js -
[![Chat on Discord](https://img.shields.io/discord/856971667393609759.svg?logo=discord)](https://clerk.com/discord) @@ -22,119 +21,38 @@ · [Request a Feature](https://feedback.clerk.com/roadmap) · -[Ask a Question](https://github.com/clerk/javascript/discussions) +[Get help](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_js)
---- - -## Overview - -ClerkJS is our foundational JavaScript library for building user management and authentication. It enables you to register, sign in, verify and manage users for your application using highly customizable flows. - ## Getting Started -### Installation - -There are two ways you can include ClerkJS in your project. You can either [import the ClerkJS npm module](#install-clerkjs-as-es-module) or [load ClerkJS with a script tag](#install-clerkjs-as-script). - -### Install ClerkJS as ES module - -```sh -npm install @clerk/clerk-js -``` - -Once you have installed the package, you will need to import the ClerkJS object constructor into your code and pass it your [Publishable Key](https://dashboard.clerk.com/last-active?path=api-keys) as a parameter. - -```js -import Clerk from '@clerk/clerk-js'; - -const clerkPublishableKey = 'pk_[publishable_key]'; -const clerk = new Clerk(clerkPublishableKey); -await clerk.load({ - // Set load options here... -}); -``` +[Clerk](https://clerk.com/?utm_source=github&utm_medium=clerk_js) is the easiest way to add authentication and user management to your JavaScript application. Add sign up, sign in, and profile management to your application in minutes. -### Install ClerkJS as script +### Prerequisites -ClerkJS can be loaded from a ` -``` - -### Build +### Installation -To build the package locally with Webpack, run: +The fastest way to get started with Clerk is by following the [JavaScript Quickstart](https://clerk.com/docs/quickstarts/javascript?utm_source=github&utm_medium=clerk_js). -```sh -npm run build -``` +You'll learn how to add the ClerkJS SDK to your application (either through ` -``` - -_For further details and examples, please refer to our [Documentation](https://clerk.com/docs?utm_source=github&utm_medium=clerk_js)._ +For further information, guides, and examples visit the [ClerkJS reference documentation](https://clerk.com/docs/references/javascript/overview?utm_source=github&utm_medium=clerk_js). ## Support You can get in touch with us in any of the following ways: - Join our official community [Discord server](https://clerk.com/discord) -- Create a [GitHub Discussion](https://github.com/clerk/javascript/discussions) -- Contact options listed on [our Support page](https://clerk.com/support?utm_source=github&utm_medium=clerk_js) +- On [our support page](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_js) ## Contributing -We're open to all community contributions! If you'd like to contribute in any way, please read [our contribution guidelines](https://github.com/clerk/javascript/blob/main/docs/CONTRIBUTING.md). +We're open to all community contributions! If you'd like to contribute in any way, please read [our contribution guidelines](https://github.com/clerk/javascript/blob/main/docs/CONTRIBUTING.md) and [code of conduct](https://github.com/clerk/javascript/blob/main/docs/CODE_OF_CONDUCT.md). ## Security diff --git a/packages/elements/README.md b/packages/elements/README.md index 9800cc4374a..75a9c0f8125 100644 --- a/packages/elements/README.md +++ b/packages/elements/README.md @@ -6,10 +6,9 @@
+

@clerk/elements

-# @clerk/elements -
[![Chat on Discord](https://img.shields.io/discord/856971667393609759.svg?logo=discord)](https://clerk.com/discord) @@ -22,13 +21,11 @@ · [Request a Feature](https://feedback.clerk.com/roadmap) · -[Ask a Question](https://github.com/clerk/javascript/discussions) +[Get help](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_elements)
---- - -## Overview +## Getting started Clerk Elements is a library of unstyled, composable components that can be used to build completely custom UIs on top of Clerk's APIs, without having to manage the underlying logic. @@ -36,41 +33,37 @@ Clerk Elements is a library of unstyled, composable components that can be used > Clerk Elements is currently in beta. It's not recommended to use it in production just yet, but it would be much appreciated if you give it a try. > If you have any feedback, please reach out to [beta-elements@clerk.dev](mailto:beta-elements@clerk.dev) or head over to the [GitHub Discussion](https://github.com/orgs/clerk/discussions/3315). -## Getting started - ### Prerequisites - Next.js `^13.5.4 || ^14.0.3` or later - React 18 or later - Node.js `>=18.17.0` or later -- You need to use the [Core 2 version](https://clerk.com/changelog/2024-04-19) (or later) of Clerk's SDKs +- Use the [Core 2 version](https://clerk.com/changelog/2024-04-19) (or later) of Clerk's SDKs +- An existing Clerk application. [Create your account for free](https://dashboard.clerk.com/sign-up?utm_source=github&utm_medium=clerk_elements). ### Installation -```sh -npm install @clerk/elements -``` - -> [!NOTE] -> If your project uses TypeScript, make sure that [`moduleResolution`](https://www.typescriptlang.org/tsconfig/#moduleResolution) in `tsconfig.json` is set to `bundler`. Otherwise, you might run into issues with resolving TypeScript types from Clerk Elements. +The fastest way to get started with Clerk Elements is by following the [Clerk Elements "Getting started" guide](https://clerk.com/docs/customization/elements/overview#getting-started?utm_source=github&utm_medium=clerk_elements). ## Usage -Once you've got your project set up, you can start building custom UIs with Clerk Elements. The following guides will show you how to build your own custom flows: +For further information, guides, and examples visit the [Clerk Elements reference documentation](https://clerk.com/docs/customization/elements/overview?utm_source=github&utm_medium=clerk_elements). + +The following guides will show you how to build your own custom flows: -- [Build a sign-in flow](https://clerk.com/docs/elements/guides/sign-in?utm_source=github&utm_medium=clerk_elements) -- [Build a sign-up flow](https://clerk.com/docs/elements/guides/sign-up?utm_source=github&utm_medium=clerk_elements) +- [Build a sign-in flow](https://clerk.com/docs/customization/elements/guides/sign-in?utm_source=github&utm_medium=clerk_elements) +- [Build a sign-up flow](https://clerk.com/docs/customization/elements/guides/sign-up?utm_source=github&utm_medium=clerk_elements) If you want to see what's possible with Clerk Elements, check out these pre-built examples from the Clerk team: -- [Sign-in examples](https://clerk.com/docs/elements/examples/sign-in?utm_source=github&utm_medium=clerk_elements) -- [Sign-up examples](https://clerk.com/docs/elements/examples/sign-up?utm_source=github&utm_medium=clerk_elements) +- [Sign-in examples](https://clerk.com/docs/customization/elements/examples/sign-in?utm_source=github&utm_medium=clerk_elements) +- [Sign-up examples](https://clerk.com/docs/customization/elements/examples/sign-up?utm_source=github&utm_medium=clerk_elements) Finally, to learn about the available components and how to use them, check out the component reference pages: -- [Common components](https://clerk.com/docs/elements/reference/common?utm_source=github&utm_medium=clerk_elements) -- [Sign-in components](https://clerk.com/docs/elements/reference/sign-in?utm_source=github&utm_medium=clerk_elements) -- [Sign-up components](https://clerk.com/docs/elements/reference/sign-up?utm_source=github&utm_medium=clerk_elements) +- [Common components](https://clerk.com/docs/customization/elements/reference/common?utm_source=github&utm_medium=clerk_elements) +- [Sign-in components](https://clerk.com/docs/customization/elements/reference/sign-in?utm_source=github&utm_medium=clerk_elements) +- [Sign-up components](https://clerk.com/docs/customization/elements/reference/sign-up?utm_source=github&utm_medium=clerk_elements) _With the beta release, only sign-up and sign-in flows are supported. Support for building the rest of Clerk's prebuilt components with Elements is actively being worked on._ @@ -79,17 +72,11 @@ _With the beta release, only sign-up and sign-in flows are supported. Support fo You can get in touch with us in any of the following ways: - Join our official community [Discord server](https://clerk.com/discord) -- Create a [GitHub Discussion](https://github.com/clerk/javascript/discussions) -- Contact options listed on [our Support page](https://clerk.com/support?utm_source=github&utm_medium=clerk_elements) +- On [our support page](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_elements) ## Contributing -We're open to all community contributions! If you'd like to contribute in any way, please read [our contribution guidelines](https://github.com/clerk/javascript/blob/main/docs/CONTRIBUTING.md). - -### Package development - -- Navigate to `examples/nextjs` and install the dependencies -- You can run the example app through `npm run dev:example` inside `packages/elements` afterwards +We're open to all community contributions! If you'd like to contribute in any way, please read [our contribution guidelines](https://github.com/clerk/javascript/blob/main/docs/CONTRIBUTING.md) and [code of conduct](https://github.com/clerk/javascript/blob/main/docs/CODE_OF_CONDUCT.md). ## Security diff --git a/packages/expo/README.md b/packages/expo/README.md index dabbb93126c..740ffbd0184 100644 --- a/packages/expo/README.md +++ b/packages/expo/README.md @@ -6,10 +6,9 @@
+

@clerk/clerk-expo

-# @clerk/clerk-expo -
[![Chat on Discord](https://img.shields.io/discord/856971667393609759.svg?logo=discord)](https://clerk.com/discord) @@ -22,146 +21,43 @@ · [Request a Feature](https://feedback.clerk.com/roadmap) · -[Ask a Question](https://github.com/clerk/javascript/discussions) +[Get help](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_expo)
---- - -## Overview - -Clerk is the easiest way to add authentication and user management to your Expo application. Add sign up, sign in, and profile management to your React Native application in minutes. - ## Getting Started +[Clerk](https://clerk.com/?utm_source=github&utm_medium=clerk_expo) is the easiest way to add authentication and user management to your Expo application. Add sign up, sign in, and profile management to your application in minutes. + ### Prerequisites - React 18 or later - Expo 50 or later - React Native 0.73 or later - Node.js `>=18.17.0` or later -- An application built using Expo +- An existing Expo application +- An existing Clerk application. [Create your account for free](https://dashboard.clerk.com/sign-up?utm_source=github&utm_medium=clerk_expo). + +### Installation -If an Expo app already exists, you can skip this section and go straight to installation. -Otherwise, you can create a new Expo app by running: +The fastest way to get started with Clerk is by following the [Expo Quickstart](https://clerk.com/docs/quickstarts/expo?utm_source=github&utm_medium=clerk_expo). -```shell -npx create-expo-app@latest my-app --template blank -cd my-app -npx expo install react-dom react-native-web @expo/metro-runtime -``` +You'll learn how to create an Expo application, install `@clerk/expo`, set up your environment keys, add ``, protect specific pages, and use Clerk's React hooks. -### Installation +## Usage -Next, install the Clerk Expo SDK: - -```shell -npm install @clerk/clerk-expo -``` - -### Usage - -Clerk requires your application to be wrapped in the `` context and passed your Publishable Key the `publishableKey` prop. - -With Expo, the entry point is typically `App.js`: - -```jsx -import { StatusBar } from 'expo-status-bar'; -import { StyleSheet, Text, View } from 'react-native'; -import { ClerkProvider } from '@clerk/clerk-expo'; - -export default function App() { - return ( - - - Open up App.js to start working on your app! - - - - ); -} - -const styles = StyleSheet.create({ - container: { - flex: 1, - backgroundColor: '#fff', - alignItems: 'center', - justifyContent: 'center', - }, -}); -``` - -A token cache is required to work with Clerk and Expo. This is entirely up to you how you handle the token cache - in this example we're going to use the `expo-secure-store` library. First, install it by running - -```shell -npm install expo-secure-store -``` - -and then add the tokenCache to your entry file, as shown here: - -```diff -import { StatusBar } from "expo-status-bar"; -import { StyleSheet, Text, View } from "react-native"; -import { ClerkProvider } from "@clerk/clerk-expo"; -+ import * as SecureStore from "expo-secure-store"; - -+ const tokenCache = { -+ getToken(key) { -+ try { -+ return SecureStore.getItemAsync(key); -+ } -+ catch (err) { -+ return null; -+ } -+ }, -+ saveToken(key, value) { -+ try { -+ return SecureStore.setItemAsync(key, value); -+ } -+ catch (err) { -+ return null; -+ } -+ }, -+}; - -export default function App() { - return ( - - - Open up App.js to start working on your app! - - - - ); -} - -const styles = StyleSheet.create({ - container: { - flex: 1, - backgroundColor: "#fff", - alignItems: "center", - justifyContent: "center", - }, -}); - -``` - -_The section above covers the basic setup. For further details and examples, please refer to our [Clerk Expo Documentation](https://clerk.com/docs?utm_source=github&utm_medium=clerk_expo)._ +For further information, guides, and examples visit the [Expo reference documentation](https://clerk.com/docs/references/expo/overview?utm_source=github&utm_medium=clerk_expo). ## Support You can get in touch with us in any of the following ways: - Join our official community [Discord server](https://clerk.com/discord) -- Create a [GitHub Discussion](https://github.com/clerk/javascript/discussions) -- Contact options listed on [our Support page](https://clerk.com/support?utm_source=github&utm_medium=clerk_expo) +- On [our support page](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_expo) ## Contributing -We're open to all community contributions! If you'd like to contribute in any way, please read [our contribution guidelines](https://github.com/clerk/javascript/blob/main/docs/CONTRIBUTING.md). +We're open to all community contributions! If you'd like to contribute in any way, please read [our contribution guidelines](https://github.com/clerk/javascript/blob/main/docs/CONTRIBUTING.md) and [code of conduct](https://github.com/clerk/javascript/blob/main/docs/CODE_OF_CONDUCT.md). ## Security diff --git a/packages/express/README.md b/packages/express/README.md index d9cc7bc6ecf..4c5e0e4a846 100644 --- a/packages/express/README.md +++ b/packages/express/README.md @@ -1,19 +1,18 @@

- +
+

@clerk/express

-# @clerk/express -
[![Chat on Discord](https://img.shields.io/discord/856971667393609759.svg?logo=discord)](https://clerk.com/discord) -[![Clerk documentation](https://img.shields.io/badge/documentation-clerk-green.svg)](https://clerk.com/docs?utm_source=github&utm_medium=express) +[![Clerk documentation](https://img.shields.io/badge/documentation-clerk-green.svg)](https://clerk.com/docs?utm_source=github&utm_medium=clerk_express) [![Follow on Twitter](https://img.shields.io/twitter/follow/ClerkDev?style=social)](https://twitter.com/intent/follow?screen_name=ClerkDev) [Changelog](https://github.com/clerk/javascript/blob/main/packages/express/CHANGELOG.md) @@ -22,67 +21,163 @@ · [Request a Feature](https://feedback.clerk.com/roadmap) · -[Ask a Question](https://github.com/clerk/javascript/discussions) +[Get help](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_express)
---- - -## Overview +## Getting Started -[Clerk](https://clerk.com?utm_source=github&utm_medium=express) is the easiest way to add authentication and user management to your Node.js application. To gain a better understanding of the Express SDK and Clerk Backend API, refer to -the Express SDK and Backend API documentation. - -## Getting started +[Clerk](https://clerk.com/?utm_source=github&utm_medium=clerk_express) is the easiest way to add authentication and user management to your Express application. Add sign up, sign in, and profile management to your application in minutes. ### Prerequisites - Node.js `>=18.17.0` or later -- Express installed (follow their [Getting started](https://expressjs.com/en/starter/installing.html) guide) +- An existing Clerk application. [Create your account for free](https://dashboard.clerk.com/sign-up?utm_source=github&utm_medium=clerk_express). +- An existing Express application (follow their [Getting started](https://expressjs.com/en/starter/installing.html) guide) -## Installation +### Installation ```sh npm install @clerk/express ``` -To build the package locally with the TypeScript compiler, run: - -```sh -npm run build -``` - ## Usage -Retrieve your Backend API key from the [API Keys](https://dashboard.clerk.com/last-active?path=api-keys) screen in your Clerk dashboard and set it as an environment variable in a `.env` file: +Navigate to the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=api-keys) and inside the **API Keys** section copy the publishable key and secret key. + +Paste your keys into an `.env` file: ```sh CLERK_PUBLISHABLE_KEY=pk_******* CLERK_SECRET_KEY=sk_****** ``` -You will then be able to access all the available methods. +Ensure that the environment variables are loaded, for example by using `dotenv` at the top of your Express application: ```js -import 'dotenv/config'; // To read CLERK_SECRET_KEY -import { clerkClient } from '@clerk/express'; +import 'dotenv/config'; + +// Rest of application +``` + +### `clerkMiddleware()` + +The `clerkMiddleware()` helper integrates Clerk authentication into your Express application. It is required to be set in the middleware chain before using other Clerk utilities, such as `requireAuth` and `getAuth()`. + +```js +import { clerkMiddleware } from '@clerk/express'; + +const app = express(); + +// Pass no parameters +app.use(clerkMiddleware()); + +// Pass a function that will run as middleware +app.use(clerkMiddleware(handler)); + +// Pass options +app.use(clerkMiddleware(options)); + +// Pass both +app.use(clerkMiddleware(handler, options)); +``` + +### `requireAuth` + +`requireAuth` is a middleware function that you can use to protect routes in your Express.js application. This function checks if the user is authenticated, and returns a 401 status code if they are not. + +`clerkMiddleware()` is required to be set in the middleware chain before this util is used. + +```js +import { clerkMiddleware, requireAuth } from '@clerk/express'; +import express from 'express'; -const { data: userList } = await clerkClient.users.getUserList(); +const app = express(); + +const port = 3000; + +// Apply centralized middleware +app.use(clerkMiddleware()); + +// Define a protected route +app.get('/protected', requireAuth, (req, res) => { + res.send('This is a protected route'); +}); + +// Start the server and listen on the specified port +app.listen(port, () => { + console.log(`Server is running on http://localhost:${port}`); +}); +``` + +### `getAuth()` + +The `getAuth()` helper retrieves authentication state from the request object. See the [Next.js reference documentation](https://clerk.com/docs/references/nextjs/get-auth) for more information on how to use it. + +```js +import { clerkMiddleware, getAuth } from '@clerk/express'; +import express from 'express'; + +const app = express(); +const port = 3000; + +// Apply centralized middleware +app.use(clerkMiddleware()); + +// Protect a route based on authorization status +hasPermission = (request, response, next) => { + const auth = getAuth(request); + + // Handle if the user is not authorized + if (!auth.has({ permission: 'org:admin:testpermission' })) { + response.status(403).send('Forbidden'); + return; + } + + return next(); +}; + +app.get('/path', requireAuth, hasPermission, (req, res) => res.json(req.auth)); + +// Start the server and listen on the specified port +app.listen(port, () => { + console.log(`Server is running on http://localhost:${port}`); +}); ``` -_For further details and examples, please refer to our [Documentation](https://clerk.com/docs/references/express/overview?utm_source=github&utm_medium=express)._ +### `clerkClient` + +[Clerk's JavaScript Backend SDK](/docs/references/backend/overview) exposes Clerk's Backend API resources and low-level authentication utilities for JavaScript environments. For example, if you wanted to get a list of all users in your application, instead of creating a fetch to Clerk's `https://api.clerk.com/v1/users` endpoint, you can use the `users.getUserList()` method provided by the JavaScript Backend SDK. + +All resource operations are mounted as sub-APIs on the `clerkClient` object. See the [reference documentation](/docs/references/backend/overview#usage) for more information. + +```js +import { clerkClient } from '@clerk/express'; +import express from 'express'; + +const app = express(); +const port = 3000; + +const users = await clerkClient.users.getUserList(); + +app.get('/users', requireAuth, (req, res) => res.json(users)); + +// Start the server and listen on the specified port +app.listen(port, () => { + console.log(`Server is running on http://localhost:${port}`); +}); +``` ## Support You can get in touch with us in any of the following ways: - Join our official community [Discord server](https://clerk.com/discord) -- Create a [GitHub Discussion](https://github.com/clerk/javascript/discussions) -- Contact options listed on [our Support page](https://clerk.com/support?utm_source=github&utm_medium=express) +- On [our support page](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_express) ## Contributing -We're open to all community contributions! If you'd like to contribute in any way, please read [our contribution guidelines](https://github.com/clerk/javascript/blob/main/docs/CONTRIBUTING.md). +We're open to all community contributions! If you'd like to contribute in any way, please read [our contribution guidelines](https://github.com/clerk/javascript/blob/main/docs/CONTRIBUTING.md) and [code of conduct](https://github.com/clerk/javascript/blob/main/docs/CODE_OF_CONDUCT.md). ## Security diff --git a/packages/fastify/README.md b/packages/fastify/README.md index bdf97c3907a..7d00d42d09f 100644 --- a/packages/fastify/README.md +++ b/packages/fastify/README.md @@ -5,11 +5,10 @@ -
+
+

@clerk/fastify

-# @clerk/fastify -
[![Chat on Discord](https://img.shields.io/discord/856971667393609759.svg?logo=discord)](https://clerk.com/discord) @@ -22,132 +21,36 @@ · [Request a Feature](https://feedback.clerk.com/roadmap) · -[Ask a Question](https://github.com/clerk/javascript/discussions) +[Get help](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_fastify)
---- - -## Overview - -[Clerk](https://clerk.com?utm_source=github&utm_medium=clerk_fastify) is the easiest way to add authentication and user management to your Fastify application. To gain a better understanding of the Clerk Backend API and SDK, refer to -the Node SDK and Backend API documentation. - ## Getting Started -To use this plugin you should first create a Clerk application and retrieve a `Secret Key` and a `Publishable Key` for you application (see [here](https://clerk.com/docs/reference/node/getting-started#set-c-l-e-r-k-s-e-c-r-e-t-key)) to be used as environment variables `CLERK_PUBLISHABLE_KEY` & `CLERK_SECRET_KEY`. +[Clerk](https://clerk.com/?utm_source=github&utm_medium=clerk_fastify) is the easiest way to add authentication and user management to your Fastify application. Add sign up, sign in, and profile management to your application in minutes. ### Prerequisites +- Fastify `^4.0.0` or later - Node.js `>=18.17.0` or later -- Fastify v4+ +- An existing Clerk application. [Create your account for free](https://dashboard.clerk.com/sign-up?utm_source=github&utm_medium=clerk_fastify). ### Installation -```shell -npm install @clerk/fastify -``` - -### Build - -```shell -npm run build -``` - -## Usage - -Retrieve your Backend API key from the [API Keys](https://dashboard.clerk.com/last-active?path=api-keys) screen in your Clerk dashboard and set it as an environment variable in a `.env` file: - -```sh -CLERK_PUBLISHABLE_KEY=pk_******* -CLERK_SECRET_KEY=sk_****** -``` - -You will then be able to access all the available methods. - -```javascript -import 'dotenv/config'; // To read CLERK_PUBLISHABLE_KEY -import Fastify from 'fastify'; -import { clerkPlugin, getAuth } from '@clerk/fastify'; -import type { FastifyInstance } from 'fastify'; - -const server: FastifyInstance = Fastify({ logger: true }); - -server.register(clerkPlugin); - -server.get('/private', async (req, reply) => { - const auth = getAuth(req); - if (!auth.userId) { - return reply.code(403).send(); - } - return { hello: 'world' }; -}); - -const start = async () => { - try { - await server.listen({ port: 3000 }); - } catch (err) { - server.log.error(err); - process.exit(1); - } -}; -start(); -``` - -### Scoped routes - -Support authenticated routes that the Clerk middleware will run as plugin in `preHandler` hook and unauthenticated routes that will not trigger the middleware using the Fastify [docs](https://www.fastify.io/docs/latest/Guides/Getting-Started/#loading-order-of-your-plugins). - -```javascript -import 'dotenv/config'; // To read CLERK_PUBLISHABLE_KEY -import Fastify from 'fastify'; -import { clerkPlugin, getAuth } from '@clerk/fastify'; -import type { FastifyReply, FastifyRequest, FastifyInstance } from 'fastify'; - -const server: FastifyInstance = Fastify({ logger: true }); - -const privateRoutes = async (fastify: FastifyInstance, _opts: any) => { - fastify.register(clerkPlugin); - - fastify.get('/private', async (req: FastifyRequest, reply: FastifyReply) => { - const auth = getAuth(req); - - if (!auth.userId) { - return reply.code(403).send(); - } - - return { hello: 'world', auth }; - }); -}; - -server.register(privateRoutes); - -server.get('/public', async (_req, _reply) => { - return { hello: 'world' }; -}); +The fastest way to get started with Clerk is by following the [Fastify Quickstart](https://clerk.com/docs/quickstarts/fastify?utm_source=github&utm_medium=clerk_fastify). -const start = async () => { - try { - await server.listen({ port: 3000 }); - } catch (err) { - server.log.error(err); - process.exit(1); - } -}; -start(); -``` +You'll learn how to install `@clerk/fastify`, set up your environment keys, and configure the `clerkPlugin`. ## Support You can get in touch with us in any of the following ways: - Join our official community [Discord server](https://clerk.com/discord) -- Create a [GitHub Discussion](https://github.com/clerk/javascript/discussions) -- Contact options listed on [our Support page](https://clerk.com/support?utm_source=github&utm_medium=clerk_fastify) +- On [our support page](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_fastify) ## Contributing -We're open to all community contributions! If you'd like to contribute in any way, please read [our contribution guidelines](https://github.com/clerk/javascript/blob/main/docs/CONTRIBUTING.md). +We're open to all community contributions! If you'd like to contribute in any way, please read [our contribution guidelines](https://github.com/clerk/javascript/blob/main/docs/CONTRIBUTING.md) and [code of conduct](https://github.com/clerk/javascript/blob/main/docs/CODE_OF_CONDUCT.md). ## Security diff --git a/packages/localizations/README.md b/packages/localizations/README.md index 0994299d562..dcd5092fc6c 100644 --- a/packages/localizations/README.md +++ b/packages/localizations/README.md @@ -6,10 +6,9 @@
+

@clerk/localizations

-# @clerk/localizations -
[![Chat on Discord](https://img.shields.io/discord/856971667393609759.svg?logo=discord)](https://clerk.com/discord) @@ -22,92 +21,37 @@ · [Request a Feature](https://feedback.clerk.com/roadmap) · -[Ask a Question](https://github.com/clerk/javascript/discussions) +[Get help](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_localizations)
---- - -### ⚠️ Important Notice: - -**Clerk officially maintains only the `en-US` (English - United States) locale. All other language translations provided within this package are community contributions.** - -## Overview +## Getting Started -Clerk offers the ability to override the strings for all of the elements in each of the Clerk Components. This allows you to provide localization for your users or change the wording to suit your brand. +When using Clerk's components you can override the strings for all of the elements. This allows you to provide localization for your users or change the wording to suit your brand. `@clerk/localizations` contains localized strings for applications using Clerk. If you found a typo, inaccuracies, or want to contribute a new language, please submit a PR and follow the [contributing guide](#contributing). -## Getting Started - -### Prerequisites - -- Clerk +> [!WARNING] +> Clerk officially **only** maintains the `en-US` (English - United States) locale. All other language translations provided within this package are community contributions. ### Installation -```shell -npm install @clerk/localizations -``` - -### Build - -```shell -npm run build -``` +The fastest way to get started with `@clerk/localizations` is by following the [localization reference documentation](https://clerk.com/docs/customization/localization#usage?utm_source=github&utm_medium=clerk_localizations). ## Usage -`@clerk/localizations` contains predefined localizations you can use: - -```javascript -import React from 'react'; -import { ClerkProvider } from '@clerk/clerk-react'; -import { frFR } from '@clerk/localizations'; - -function App() { - return ( - -
Hello from clerk
- - ); -} - -export default App; -``` - -You can also provide your own localization: - -```javascript -import React from 'react'; -import { ClerkProvider } from '@clerk/clerk-react'; - -const localization = { - socialButtonsBlockButton: 'Sign In with {{provider|titleize}}', -}; - -function App() { - return ( - -
Hello from clerk
- - ); -} - -export default App; -``` +Furthermore, you can learn how to [update a localization](https://clerk.com/docs/customization/localization#adding-or-updating-a-localization?utm_source=github&utm_medium=clerk_localizations) or [use a custom one](https://clerk.com/docs/customization/localization#custom-localizations?utm_source=github&utm_medium=clerk_localizations). ## Support You can get in touch with us in any of the following ways: - Join our official community [Discord server](https://clerk.com/discord) -- Create a [GitHub Discussion](https://github.com/clerk/javascript/discussions) -- Contact options listed on [our Support page](https://clerk.com/support?utm_source=github&utm_medium=clerk_localizations) +- On [our support page](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_localizations) ## Contributing -We're open to all community contributions! If you'd like to contribute in any way, please read [our contribution guidelines](https://github.com/clerk/javascript/blob/main/docs/CONTRIBUTING.md). +We're open to all community contributions! If you'd like to contribute in any way, please read [our contribution guidelines](https://github.com/clerk/javascript/blob/main/docs/CONTRIBUTING.md) and [code of conduct](https://github.com/clerk/javascript/blob/main/docs/CODE_OF_CONDUCT.md). ### Adding a new localization key diff --git a/packages/nextjs/README.md b/packages/nextjs/README.md index 78d076f7a5a..3a6fee56c1c 100644 --- a/packages/nextjs/README.md +++ b/packages/nextjs/README.md @@ -6,10 +6,9 @@
+

@clerk/nextjs

-# @clerk/nextjs -
[![Chat on Discord](https://img.shields.io/discord/856971667393609759.svg?logo=discord)](https://clerk.com/discord) @@ -22,101 +21,41 @@ · [Request a Feature](https://feedback.clerk.com/roadmap) · -[Ask a Question](https://github.com/clerk/javascript/discussions) +[Get help](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_nextjs)
---- - -## Overview - -Clerk is the easiest way to add authentication and user management to your Next.js application. Add sign up, sign in, -and profile management to your application in minutes. - ## Getting Started +[Clerk](https://clerk.com/?utm_source=github&utm_medium=clerk_nextjs) is the easiest way to add authentication and user management to your Next.js application. Add sign up, sign in, and profile management to your application in minutes. + ### Prerequisites - Next.js 13.0.4 or later - React 18 or later - Node.js `>=18.17.0` or later +- An existing Clerk application. [Create your account for free](https://dashboard.clerk.com/sign-up?utm_source=github&utm_medium=clerk_nextjs). ### Installation -```sh -npm install @clerk/nextjs -``` - -### Build - -To build the package locally with the TypeScript compiler, run: - -```sh -npm run build -``` - -To build the package in watch mode, run the following: +The fastest way to get started with Clerk is by following the [Next.js Quickstart](https://clerk.com/docs/quickstarts/nextjs?utm_source=github&utm_medium=clerk_nextjs). -```sh -npm run dev -``` +You'll learn how to install `@clerk/nextjs`, set up your environment keys, add `` to your application, use the Clerk middleware, and use Clerk's prebuilt components. ## Usage -Clerk requires your application to be wrapped in the `` context. - -Set `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` to your Publishable Key in your `.env.local` file to make the environment -variable accessible to the Provider. - -```sh -NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_(test|live)_xxxxxxx -``` - -An implementation of `` with our flexible Control Components to build an authentication flow -in `pages/_app.js`: - -```jsx -import { ClerkProvider, RedirectToSignIn, SignedIn, SignedOut, UserButton } from '@clerk/nextjs'; - -function MyApp({ Component, pageProps }) { - return ( - - <> - - <> -
- -
- - - - - - - - - ); -} - -export default MyApp; -``` - -_For further details and examples, please refer to -our [Documentation](https://clerk.com/docs?utm_source=github&utm_medium=clerk_nextjs)._ +For further information, guides, and examples visit the [Next.js reference documentation](https://clerk.com/docs/references/nextjs/overview?utm_source=github&utm_medium=clerk_nextjs). ## Support You can get in touch with us in any of the following ways: - Join our official community [Discord server](https://clerk.com/discord) -- Create a [GitHub Discussion](https://github.com/clerk/javascript/discussions) -- Contact options listed on [our Support page](https://clerk.com/support?utm_source=github&utm_medium=clerk_nextjs) +- On [our support page](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_nextjs) ## Contributing -We're open to all community contributions! If you'd like to contribute in any way, please -read [our contribution guidelines](https://github.com/clerk/javascript/blob/main/docs/CONTRIBUTING.md)) -. +We're open to all community contributions! If you'd like to contribute in any way, please read [our contribution guidelines](https://github.com/clerk/javascript/blob/main/docs/CONTRIBUTING.md) and [code of conduct](https://github.com/clerk/javascript/blob/main/docs/CODE_OF_CONDUCT.md). ## Security @@ -124,8 +63,7 @@ read [our contribution guidelines](https://github.com/clerk/javascript/blob/main `@clerk/nextjs` is provided **"as is"** without any **warranty**. Use at your own risk. -_For more information and to report security issues, please refer to -our [security documentation](https://github.com/clerk/javascript/blob/main/docs/SECURITY.md)._ +_For more information and to report security issues, please refer to our [security documentation](https://github.com/clerk/javascript/blob/main/docs/SECURITY.md)._ ## License diff --git a/packages/react/README.md b/packages/react/README.md index 63c7d28fb9f..ef73911424d 100644 --- a/packages/react/README.md +++ b/packages/react/README.md @@ -6,10 +6,9 @@
+

@clerk/clerk-react

-# @clerk/clerk-react -
[![Chat on Discord](https://img.shields.io/discord/856971667393609759.svg?logo=discord)](https://clerk.com/discord) @@ -22,89 +21,40 @@ · [Request a Feature](https://feedback.clerk.com/roadmap) · -[Ask a Question](https://github.com/clerk/javascript/discussions) +[Get help](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_react)
---- - -## Overview - -Clerk is the easiest way to add authentication and user management to your React application. Add sign up, sign in, and profile management to your application in minutes. - ## Getting Started +[Clerk](https://clerk.com/?utm_source=github&utm_medium=clerk_react) is the easiest way to add authentication and user management to your React application. Add sign up, sign in, and profile management to your application in minutes. + ### Prerequisites -- React v18+ +- React 18 or later - Node.js `>=18.17.0` or later +- An existing Clerk application. [Create your account for free](https://dashboard.clerk.com/sign-up?utm_source=github&utm_medium=clerk_react). ### Installation -```sh -npm install @clerk/clerk-react -``` - -### Build - -```sh -npm run build -``` - -To build the package in watch mode, run the following: +The fastest way to get started with Clerk is by following the [React Quickstart](https://clerk.com/docs/quickstarts/react?utm_source=github&utm_medium=clerk_react). -```sh -npm run dev -``` +You'll learn how to create a new React application, install `@clerk/clerk-react`, set up your environment keys, add ``, and use Clerk's prebuilt components. ## Usage -Clerk requires your application to be wrapped in the `` context. - -If using Vite, set `VITE_CLERK_PUBLISHABLE_KEY` to your Publishable key in your `.env.local` file to make the environment variable accessible on `process.env` and pass it as the `publishableKey` prop. - -```jsx -import { render } from 'react-dom'; - -import { ClerkProvider, SignedIn, SignedOut, SignInButton, UserButton } from '@clerk/clerk-react'; - -const publishableKey = process.env.VITE_CLERK_PUBLISHABLE_KEY; - -render( - - - , - document.getElementById('root'), -); - -function App() { - return ( - <> -

Hello Clerk!

- - - - - - - - ); -} -``` - -_For further details and examples, please refer to our [Documentation](https://clerk.com/docs?utm_source=github&utm_medium=clerk_react)._ +For further information, guides, and examples visit the [React reference documentation](https://clerk.com/docs/references/react/overview?utm_source=github&utm_medium=clerk_react). ## Support You can get in touch with us in any of the following ways: - Join our official community [Discord server](https://clerk.com/discord) -- Create a [GitHub Discussion](https://github.com/clerk/javascript/discussions) -- Contact options listed on [our Support page](https://clerk.com/support?utm_source=github&utm_medium=clerk_react) +- On [our support page](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_react) ## Contributing -We're open to all community contributions! If you'd like to contribute in any way, please read [our contribution guidelines](https://github.com/clerk/javascript/blob/main/docs/CONTRIBUTING.md). +We're open to all community contributions! If you'd like to contribute in any way, please read [our contribution guidelines](https://github.com/clerk/javascript/blob/main/docs/CONTRIBUTING.md) and [code of conduct](https://github.com/clerk/javascript/blob/main/docs/CODE_OF_CONDUCT.md). ## Security diff --git a/packages/remix/README.md b/packages/remix/README.md index 492b6ab3d8d..7321ce2ef47 100644 --- a/packages/remix/README.md +++ b/packages/remix/README.md @@ -6,10 +6,9 @@
+

@clerk/remix

-# @clerk/remix -
[![Chat on Discord](https://img.shields.io/discord/856971667393609759.svg?logo=discord)](https://clerk.com/discord) @@ -22,114 +21,41 @@ · [Request a Feature](https://feedback.clerk.com/roadmap) · -[Ask a Question](https://github.com/clerk/javascript/discussions) +[Get help](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_remix)
---- - -## Overview - -Clerk is the easiest way to add authentication and user management to your Remix application. Add sign up, sign in, and profile management to your application in minutes. - ## Getting Started +[Clerk](https://clerk.com/?utm_source=github&utm_medium=clerk_remix) is the easiest way to add authentication and user management to your Remix application. Add sign up, sign in, and profile management to your application in minutes. + ### Prerequisites - Remix `^2.0.0` or later - React 18 or later - Node.js `>=18.17.0` or later +- An existing Clerk application. [Create your account for free](https://dashboard.clerk.com/sign-up?utm_source=github&utm_medium=clerk_remix). ### Installation -```sh -npm install @clerk/remix -``` - -### Build +The fastest way to get started with Clerk is by following the [Remix Quickstart](https://clerk.com/docs/quickstarts/remix?utm_source=github&utm_medium=clerk_remix). -To build the package locally with the TypeScript compiler, run: - -```sh -npm run build -``` - -To build the package in watch mode, run the following: - -```sh -npm run dev -``` +You'll learn how to install `@clerk/remix`, set up your environment keys, configure `rootAuthLoader` & `ClerkApp`, and protect your pages. ## Usage -Make sure the following environment variables are set in a `.env` file: - -```sh -CLERK_PUBLISHABLE_KEY=[publishable-key] -CLERK_SECRET_KEY=[backend-secret-key] -``` - -You can get these from the [API Keys](https://dashboard.clerk.com/last-active?path=api-keys) screen in your Clerk dashboard. - -To initialize Clerk with your Remix application, you will need to make three modifications to `app/root.jsx`: - -1. Export `rootAuthLoader` as `loader` -1. Wrap the default export with `ClerkApp` - -```jsx -import { rootAuthLoader } from '@clerk/remix/ssr.server'; -import { ClerkApp } from '@clerk/remix'; - -export const loader = args => rootAuthLoader(args); - -function App() { - return [...]; -} - -export default ClerkApp(App); -``` - -After those changes are made, you can use Clerk components in your routes. - -For example, in `app/routes/index.jsx`: - -```jsx -import { SignedIn, SignedOut, SignInButton, UserButton } from '@clerk/remix'; - -export default function Index() { - return ( -
-

Hello Clerk!

- - - - - - -
- ); -} -``` - -_For further details and examples, please refer to our [Documentation](https://clerk.com/docs/quickstarts/remix?utm_source=github&utm_medium=clerk_remix)._ +For further information, guides, and examples visit the [Remix reference documentation](https://clerk.com/docs/references/remix/clerk-app?utm_source=github&utm_medium=clerk_remix). ## Support You can get in touch with us in any of the following ways: - Join our official community [Discord server](https://clerk.com/discord) -- Create a [GitHub Discussion](https://github.com/clerk/javascript/discussions) -- Contact options listed on [our Support page](https://clerk.com/support?utm_source=github&utm_medium=clerk_remix) +- On [our support page](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_remix) ## Contributing -We're open to all community contributions! If you'd like to contribute in any way, please read [our contribution guidelines](https://github.com/clerk/javascript/blob/main/docs/CONTRIBUTING.md). +We're open to all community contributions! If you'd like to contribute in any way, please read [our contribution guidelines](https://github.com/clerk/javascript/blob/main/docs/CONTRIBUTING.md) and [code of conduct](https://github.com/clerk/javascript/blob/main/docs/CODE_OF_CONDUCT.md). ## Security diff --git a/packages/sdk-node/README.md b/packages/sdk-node/README.md index fe1e015d537..e1fdedb1b9d 100644 --- a/packages/sdk-node/README.md +++ b/packages/sdk-node/README.md @@ -6,10 +6,9 @@
+

@clerk/clerk-sdk-node

-# @clerk/clerk-sdk-node -
[![Chat on Discord](https://img.shields.io/discord/856971667393609759.svg?logo=discord)](https://clerk.com/discord) @@ -22,66 +21,37 @@ · [Request a Feature](https://feedback.clerk.com/roadmap) · -[Ask a Question](https://github.com/clerk/javascript/discussions) +[Get help](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_sdk_node)
---- - -## Overview - -[Clerk](https://clerk.com?utm_source=github&utm_medium=clerk_sdk_node) is the easiest way to add authentication and user management to your Node.js application. To gain a better understanding of the Clerk Backend API and SDK, refer to -the Node SDK and Backend API documentation. +## Getting Started -## Getting started +[Clerk](https://clerk.com/?utm_source=github&utm_medium=clerk_sdk_node) is the easiest way to add authentication and user management to your Node.js application. Add sign up, sign in, and profile management to your application in minutes. ### Prerequisites - Node.js `>=18.17.0` or later +- An existing Clerk application. [Create your account for free](https://dashboard.clerk.com/sign-up?utm_source=github&utm_medium=clerk_sdk_node). -## Installation - -```sh -npm install @clerk/clerk-sdk-node -``` - -To build the package locally with the TypeScript compiler, run: +### Installation -```sh -npm run build -``` +The fastest way to get started with Clerk is by following the [Clerk Node.js Quickstart](https://clerk.com/docs/references/nodejs/overview?utm_source=github&utm_medium=clerk_sdk_node). ## Usage -Retrieve your Backend API key from the [API Keys](https://dashboard.clerk.com/last-active?path=api-keys) screen in your Clerk dashboard and set it as an environment variable in a `.env` file: - -```sh -CLERK_PUBLISHABLE_KEY=pk_******* -CLERK_SECRET_KEY=sk_****** -``` - -You will then be able to access all the available methods. - -```js -import 'dotenv/config'; // To read CLERK_SECRET_KEY -import clerk from '@clerk/clerk-sdk-node'; - -const { data: userList } = await clerk.users.getUserList(); -``` - -_For further details and examples, please refer to our [Documentation](https://clerk.com/docs/reference/node/getting-started?utm_source=github&utm_medium=clerk_sdk_node)._ +You can use all [available methods](https://clerk.com/docs/references/nodejs/available-methods?utm_source=github&utm_medium=clerk_sdk_node) from the Backend SDK. ## Support You can get in touch with us in any of the following ways: - Join our official community [Discord server](https://clerk.com/discord) -- Create a [GitHub Discussion](https://github.com/clerk/javascript/discussions) -- Contact options listed on [our Support page](https://clerk.com/support?utm_source=github&utm_medium=clerk_sdk_node) +- On [our support page](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_sdk_node) ## Contributing -We're open to all community contributions! If you'd like to contribute in any way, please read [our contribution guidelines](https://github.com/clerk/javascript/blob/main/docs/CONTRIBUTING.md). +We're open to all community contributions! If you'd like to contribute in any way, please read [our contribution guidelines](https://github.com/clerk/javascript/blob/main/docs/CONTRIBUTING.md) and [code of conduct](https://github.com/clerk/javascript/blob/main/docs/CODE_OF_CONDUCT.md). ## Security diff --git a/packages/tanstack-start/README.md b/packages/tanstack-start/README.md index e0cf63f553c..0b1fa24ca7e 100644 --- a/packages/tanstack-start/README.md +++ b/packages/tanstack-start/README.md @@ -6,39 +6,38 @@
+

@clerk/tanstack-start

-# @clerk/tanstack-start -
[![Chat on Discord](https://img.shields.io/discord/856971667393609759.svg?logo=discord)](https://clerk.com/discord) [![Clerk documentation](https://img.shields.io/badge/documentation-clerk-green.svg)](https://clerk.com/docs?utm_source=github&utm_medium=clerk_tanstack_start) [![Follow on Twitter](https://img.shields.io/twitter/follow/ClerkDev?style=social)](https://twitter.com/intent/follow?screen_name=ClerkDev) -[Changelog](https://github.com/clerk/javascript/blob/main/packages/nextjs/CHANGELOG.md) +[Changelog](https://github.com/clerk/javascript/blob/main/packages/tanstack-start/CHANGELOG.md) · [Report a Bug](https://github.com/clerk/javascript/issues/new?assignees=&labels=needs-triage&projects=&template=BUG_REPORT.yml) · [Request a Feature](https://feedback.clerk.com/roadmap) · -[Ask a Question](https://github.com/clerk/javascript/discussions) +[Get help](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_tanstack_start)
---- - -## Overview +## Getting Started -Clerk is the easiest way to add authentication and user management to your TanStack Start application. Add sign up, sign in, -and profile management to your application in minutes. +[Clerk](https://clerk.com/?utm_source=github&utm_medium=clerk_tanstack_start) is the easiest way to add authentication and user management to your Tanstack Start application. Add sign up, sign in, and profile management to your application in minutes. -## Getting Started +> [!WARNING] > `@clerk/tanstack-start` is currently in beta. It's not recommended to use it in production just yet, but it would be much appreciated if you give it a try. ### Prerequisites +- Tanstack Start `^1.49.1` or later +- Tanstack Router `^1.49.1` or later - React 18 or later - Node.js `>=18.17.0` or later +- An existing Clerk application. [Create your account for free](https://dashboard.clerk.com/sign-up?utm_source=github&utm_medium=clerk_tanstack_start). ### Installation @@ -46,34 +45,18 @@ and profile management to your application in minutes. npm install @clerk/tanstack-start ``` -### Build - -To build the package locally with the TypeScript compiler, run: - -```sh -npm run build -``` - -To build the package in watch mode, run the following: - -```sh -npm run dev -``` - ## Usage Make sure the following environment variables are set in a `.env` file: ```sh -CLERK_PUBLISHABLE_KEY=[publishable-key] -CLERK_SECRET_KEY=[backend-secret-key] +CLERK_PUBLISHABLE_KEY=pk_test_xxx +CLERK_SECRET_KEY=sk_test_xxx ``` You can get these from the [API Keys](https://dashboard.clerk.com/last-active?path=api-keys) screen in your Clerk dashboard. -To initialize Clerk with your TanStack Start application, you will need to make one modification to `app/routes/_root.tsx`: - -- Wrap the children of the `RootComponent` with `` +To initialize Clerk with your TanStack Start application, you will need to make one modification to `app/routes/_root.tsx`. Wrap the children of the `RootComponent` with `` ```tsx import { ClerkProvider } from '@clerk/tanstack-start' @@ -180,26 +163,22 @@ function Home() { You can get in touch with us in any of the following ways: - Join our official community [Discord server](https://clerk.com/discord) -- Create a [GitHub Discussion](https://github.com/clerk/javascript/discussions) -- Contact options listed on [our Support page](https://clerk.com/support?utm_source=github&utm_medium=clerk_tanstack_start) +- On [our support page](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_tanstack_start) ## Contributing -We're open to all community contributions! If you'd like to contribute in any way, please -read [our contribution guidelines](https://github.com/clerk/javascript/blob/main/docs/CONTRIBUTING.md)) -. +We're open to all community contributions! If you'd like to contribute in any way, please read [our contribution guidelines](https://github.com/clerk/javascript/blob/main/docs/CONTRIBUTING.md) and [code of conduct](https://github.com/clerk/javascript/blob/main/docs/CODE_OF_CONDUCT.md). ## Security -`@clerk/nextjs` follows good practices of security, but 100% security cannot be assured. +`@clerk/tanstack-start` follows good practices of security, but 100% security cannot be assured. -`@clerk/nextjs` is provided **"as is"** without any **warranty**. Use at your own risk. +`@clerk/tanstack-start` is provided **"as is"** without any **warranty**. Use at your own risk. -_For more information and to report security issues, please refer to -our [security documentation](https://github.com/clerk/javascript/blob/main/docs/SECURITY.md)._ +_For more information and to report security issues, please refer to our [security documentation](https://github.com/clerk/javascript/blob/main/docs/SECURITY.md)._ ## License This project is licensed under the **MIT license**. -See [LICENSE](https://github.com/clerk/javascript/blob/main/packages/nextjs/LICENSE) for more information. +See [LICENSE](https://github.com/clerk/javascript/blob/main/packages/tanstack-start/LICENSE) for more information. diff --git a/packages/testing/README.md b/packages/testing/README.md index c6b0588bec1..c0741cd9769 100644 --- a/packages/testing/README.md +++ b/packages/testing/README.md @@ -5,11 +5,10 @@ -
+
+

@clerk/testing

-# @clerk/testing -
[![Chat on Discord](https://img.shields.io/discord/856971667393609759.svg?logo=discord)](https://clerk.com/discord) @@ -22,13 +21,11 @@ · [Request a Feature](https://feedback.clerk.com/roadmap) · -[Ask a Question](https://github.com/clerk/javascript/discussions) +[Get help](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_testing)
---- - -## Overview +## Getting started This package provides utilities for testing Clerk applications. @@ -37,8 +34,6 @@ It currently supports the following testing frameworks: - [Playwright](https://playwright.dev/), a Node.js library to automate browsers and web pages. - [Cypress](https://www.cypress.io/), a JavaScript-based end-to-end testing framework. -## Getting started - ### Prerequisites - Node.js `>=18.17.0` or later @@ -52,189 +47,21 @@ npm install @clerk/testing --save-dev ## Usage -### Playwright - -Firstly, add your Clerk keys (`CLERK_PUBLISHABLE_KEY` and `CLERK_SECRET_KEY`) to your environment variables file (e.g. `.env.local` or `.env.`). -You can find these keys in your Clerk Dashboard. - -All Playwright related utilities are exported from `@clerk/testing/playwright`. Make sure that your import paths are correct! - -In your global setup file for Playwright, you must use the `clerkSetup` function to set up Clerk for your tests. - -```typescript -// global-setup.ts -import { clerkSetup } from '@clerk/testing/playwright'; -import { test as setup } from '@playwright/test'; - -setup('global setup', async ({ }) => { - await clerkSetup(); - ... -}); -``` - -Then, you can use the `setupClerkTestingToken` function to bypass bot protection in your tests. - -```typescript -// my-test.spec.ts -import { setupClerkTestingToken } from "@clerk/testing/playwright"; -import { test } from "@playwright/test"; - -test("sign up", async ({ page }) => { - await setupClerkTestingToken({ page }); - - await page.goto("/sign-up"); - ... -}); -``` - -### Cypress - -⚠️ **Please note:** Its intended usage is for **end-to-end** testing only. This package does not support unit testing with Cypress. - -Firstly, add your Clerk keys (`CLERK_PUBLISHABLE_KEY` and `CLERK_SECRET_KEY`) to your environment variables file (e.g. `.env.local` or `.env.`). -You can find these keys in your Clerk Dashboard. - -All Cypress related utilities are exported from `@clerk/testing/cypress`. Make sure that your import paths are correct! - -In your `cypress.config.ts`, you must use the `clerkSetup` function to set up Clerk for your tests. -Keep in mind that you must pass the Cypress `config` object to the `clerkSetup` function and also return the new config object from the `setupNodeEvents` function. - -```typescript -// cypress.config.ts -import { clerkSetup } from '@clerk/testing/cypress'; -import { defineConfig } from 'cypress'; - -export default defineConfig({ - e2e: { - setupNodeEvents(on, config) { - return clerkSetup({ config }); - }, - baseUrl: 'http://localhost:3000', // your app's URL - }, -}); -``` - -Then, you can use the `setupClerkTestingToken` function to bypass bot protection in your tests. - -```typescript -// cypress/e2e/app.cy.ts -import { setupClerkTestingToken } from "@clerk/testing/cypress"; - -it("sign up", () => { - setupClerkTestingToken(); - - cy.visit('/sign-up'); - ... -}); -``` - -## Cypress Custom commands - -This package also provides custom commands to sign in/sign out with Clerk in your Cypress tests without having to interact with the UI. -To use these commands, you must import them in your `cypress/support/commands.ts` file. - -```ts -// cypress/support/commands.ts -/// -import { addClerkCommands } from '@clerk/testing/cypress'; -addClerkCommands({ Cypress, cy }); +Learn how to use `@clerk/testing` with different frameworks: -export {}; -``` - -### `cy.clerkSignIn` - -The `cy.clerkSignIn` command is used to sign in a user using Clerk. This custom command supports only the following first factor strategies: - -- Password -- Phone code -- Email code - -**Note:** Multi-factor authentication is not supported. - -This helper internally uses the `setupClerkTestingToken`, so you don't need to call it separately. - -**Prerequisites** - -- You must call `cy.visit` before calling this command. -- Navigate to a non-protected page that loads Clerk before using this command. - -**Parameters** - -- `signInParams`: The sign-in object. - - `strategy`: The sign-in strategy. Supported strategies are `'password'`, `'phone_code'`, and `'email_code'`. - - `identifier`: The user's identifier. This could be a username, a phone number, or an email. - - `password`: The user's password. This is required only if the strategy is `'password'`. - -**Strategy Specifics** - -- **Password:** The command will sign in the user using the provided password and identifier. -- **Phone Code:** You must have a user with a test phone number as an identifier (e.g., `+15555550100`). -- **Email Code:** You must have a user with a test email as an identifier (e.g., `your_email+clerk_test@example.com`). - -**Example** - -```ts -it('sign in', () => { - cy.visit(`/`); - cy.clerkSignIn({ strategy: 'phone_code', identifier: '+15555550100' }); - cy.visit('/protected'); -}); -``` - -### `cy.clerkSignOut` - -The `cy.clerkSignOut` command is used to sign out the current user using Clerk. - -**Prerequisites** - -- You must call `cy.visit` before calling this command. -- Navigate to a page that loads Clerk before using this command. - -**Parameters** - -- `signOutOptions`: A `SignOutOptions` object. - -**Example** - -```ts -it('sign out', () => { - cy.visit(`/`); - cy.clerkSignIn({ strategy: 'phone_code', identifier: '+15555550100' }); - cy.visit('/protected'); - cy.clerkSignOut(); -}); -``` - -### `cy.clerkLoaded` - -The `cy.clerkLoaded` command asserts that Clerk has been loaded. - -**Prerequisites** - -- You must call `cy.visit` before calling this command. -- Navigate to a page that loads Clerk before using this command. - -**Example** - -```ts -it('check Clerk loaded', () => { - cy.visit(`/`); - cy.clerkLoaded(); -}); -``` +- [Testing with Playwright](https://clerk.com/docs/testing/playwright?utm_source=github&utm_medium=clerk_testing) +- [Testing with Cypress](https://clerk.com/docs/testing/cypress?utm_source=github&utm_medium=clerk_testing) ## Support You can get in touch with us in any of the following ways: - Join our official community [Discord server](https://clerk.com/discord) -- Create a [GitHub Discussion](https://github.com/clerk/javascript/discussions) -- Contact options listed on [our Support page](https://clerk.com/support?utm_source=github&utm_medium=clerk_testing) +- On [our support page](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_testing) ## Contributing -We're open to all community contributions! If you'd like to contribute in any way, please read [our contribution guidelines](https://github.com/clerk/javascript/blob/main/docs/CONTRIBUTING.md). +We're open to all community contributions! If you'd like to contribute in any way, please read [our contribution guidelines](https://github.com/clerk/javascript/blob/main/docs/CONTRIBUTING.md) and [code of conduct](https://github.com/clerk/javascript/blob/main/docs/CODE_OF_CONDUCT.md). ## Security diff --git a/packages/themes/README.md b/packages/themes/README.md index 9dc2fca65fc..80efdbda980 100644 --- a/packages/themes/README.md +++ b/packages/themes/README.md @@ -6,10 +6,9 @@
+

@clerk/themes

-# @clerk/themes -
[![Chat on Discord](https://img.shields.io/discord/856971667393609759.svg?logo=discord)](https://clerk.com/discord) @@ -22,45 +21,40 @@ · [Request a Feature](https://feedback.clerk.com/roadmap) · -[Ask a Question](https://github.com/clerk/javascript/discussions) +[Get help](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_themes)
---- - -## Overview +## Getting Started -Clerk is the easiest way to add authentication and user management to your themes application. Add sign up, sign in, and profile management to your React Native application in minutes. +[Clerk](https://clerk.com/?utm_source=github&utm_medium=clerk_themes) is the easiest way to add authentication and user management to your application. Add sign up, sign in, and profile management to your application in minutes. -## Getting Started +You can customize the appearance of Clerk components by using the [appearance prop](https://clerk.com/docs/customization/overview?utm_source=github&utm_medium=clerk_themes). `@clerk/themes` offers prebuilt themes. ### Prerequisites -TODO +- An existing Clerk application. [Create your account for free](https://dashboard.clerk.com/sign-up?utm_source=github&utm_medium=clerk_themes). ### Installation -TODO - -### Build - -TODO +```shell +npm install @clerk/themes +``` ## Usage -TODO +Learn how to [apply custom themes](https://clerk.com/docs/customization/themes#usage?utm_source=github&utm_medium=clerk_themes) in the reference documentation. ## Support You can get in touch with us in any of the following ways: - Join our official community [Discord server](https://clerk.com/discord) -- Create a [GitHub Discussion](https://github.com/clerk/javascript/discussions) -- Contact options listed on [our Support page](https://clerk.com/support?utm_source=github&utm_medium=clerk_themes) +- On [our support page](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_themes) ## Contributing -We're open to all community contributions! If you'd like to contribute in any way, please read [our contribution guidelines](https://github.com/clerk/javascript/blob/main/docs/CONTRIBUTING.md). +We're open to all community contributions! If you'd like to contribute in any way, please read [our contribution guidelines](https://github.com/clerk/javascript/blob/main/docs/CONTRIBUTING.md) and [code of conduct](https://github.com/clerk/javascript/blob/main/docs/CODE_OF_CONDUCT.md). ## Security diff --git a/packages/types/README.md b/packages/types/README.md index 38a690e7f21..6e712b40bb1 100644 --- a/packages/types/README.md +++ b/packages/types/README.md @@ -6,10 +6,9 @@
+

@clerk/types

-# @clerk/types -
[![Chat on Discord](https://img.shields.io/discord/856971667393609759.svg?logo=discord)](https://clerk.com/discord) @@ -22,41 +21,28 @@ · [Request a Feature](https://feedback.clerk.com/roadmap) · -[Ask a Question](https://github.com/clerk/javascript/discussions) +[Get help](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_types)
--- -## Overview - -This package provides the TypeScript type declarations for Clerk libraries. - ## Getting Started -It is worth noting that Clerk packages automatically include their type declarations when installed so adding this package manually is not typically necessary. - -### Installation - -```sh -npm install --save-dev @clerk/types -``` - -### Build +This package provides the TypeScript type declarations for Clerk's SDKs. -```sh -npm run build -``` +> [!NOTE] +> Clerk's SDKs automatically include their own type definitions so typically it's not necessary to install `@clerk/types` separately. -To build types in watch mode, run the following: +### Installation ```sh -npm run dev +npm install @clerk/types --save-dev ``` ## Usage -Example implementation: +Import types from `@clerk/types` like so: ```ts import type { OAuthStrategy } from '@clerk/types'; @@ -68,19 +54,18 @@ export type OAuthProps = { }; ``` -_For further details and examples, please refer to our [Documentation](https://clerk.com/docs?utm_source=github&utm_medium=clerk_types)._ +You can also [override Clerk interfaces with custom types](https://clerk.com/docs/guides/custom-types?utm_source=github&utm_medium=clerk_types). ## Support You can get in touch with us in any of the following ways: - Join our official community [Discord server](https://clerk.com/discord) -- Create a [GitHub Discussion](https://github.com/clerk/javascript/discussions) -- Contact options listed on [our Support page](https://clerk.com/support?utm_source=github&utm_medium=clerk_types) +- On [our support page](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_types) ## Contributing -We're open to all community contributions! If you'd like to contribute in any way, please read [our contribution guidelines](https://github.com/clerk/javascript/blob/main/docs/CONTRIBUTING.md). +We're open to all community contributions! If you'd like to contribute in any way, please read [our contribution guidelines](https://github.com/clerk/javascript/blob/main/docs/CONTRIBUTING.md) and [code of conduct](https://github.com/clerk/javascript/blob/main/docs/CODE_OF_CONDUCT.md). ## Security diff --git a/packages/upgrade/README.md b/packages/upgrade/README.md index 23df9f0b989..4ad77099c75 100644 --- a/packages/upgrade/README.md +++ b/packages/upgrade/README.md @@ -6,10 +6,9 @@
+

@clerk/upgrade

-# @clerk/upgrade -
[![Chat on Discord](https://img.shields.io/discord/856971667393609759.svg?logo=discord)](https://clerk.com/discord) @@ -22,29 +21,29 @@ · [Request a Feature](https://feedback.clerk.com/roadmap) · -[Ask a Question](https://github.com/clerk/javascript/discussions) +[Get help](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_upgrade)
---- - -## Overview +## Getting Started A tool that helps with upgrading major versions of Clerk's SDKs. -## Getting Started - ### Prerequisites - Node.js `>=18.17.0` or later -### Usage +## Usage + +Navigate to the application you want to upgrade and run the following in your terminal: ```sh npx @clerk/upgrade ``` -## Caveats +Fill out the questionnaire and the CLI will show you the required changes. + +### Caveats This tool uses regular expressions to scan for patterns that match breaking changes. This makes it run substantially faster and makes it more accessible for us at Clerk to author matchers for each breaking change, however it means that _we cannot gurarantee 100% accuracy of the results_. As such, it's important to treat this as a tool that can help you to complete your major version upgrades, rather than an automatic fix to all issues. @@ -65,12 +64,11 @@ Overall, there's a very good chance that this tool catches everything, but it's You can get in touch with us in any of the following ways: - Join our official community [Discord server](https://clerk.com/discord) -- Create a [GitHub Discussion](https://github.com/clerk/javascript/discussions) -- Contact options listed on [our Support page](https://clerk.com/support?utm_source=github&utm_medium=clerk_upgrade) +- On [our support page](https://clerk.com/contact/support?utm_source=github&utm_medium=clerk_upgrade) ## Contributing -We're open to all community contributions! If you'd like to contribute in any way, please read [our contribution guidelines](https://github.com/clerk/javascript/blob/main/docs/CONTRIBUTING.md). +We're open to all community contributions! If you'd like to contribute in any way, please read [our contribution guidelines](https://github.com/clerk/javascript/blob/main/docs/CONTRIBUTING.md) and [code of conduct](https://github.com/clerk/javascript/blob/main/docs/CODE_OF_CONDUCT.md). ## Security