Support experimental_ignoreInterstitial option and use it for api routes

[dimkl]

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

Packages affected

• @clerk/clerk-js
• @clerk/clerk-react
• @clerk/nextjs
• @clerk/remix
• @clerk/types
• @clerk/themes
• @clerk/localizations
• @clerk/clerk-expo
• @clerk/backend
• @clerk/clerk-sdk-node
• @clerk/shared
• @clerk/fastify
• @clerk/chrome-extension
• gatsby-plugin-clerk
• build/tooling/chore

Description

• npm test runs as expected.
• npm run build runs as expected.

Handle interstitial as signed-out for API routes.
Example usages

// 1. @clerk/backend
import { clerkClient } from "@clerk/backend";

clerkClient.authenticateRequest({
  experimental_ignoreInterstitial: true
});

// 2. @clerk/clerk-sdk-node with optional authentication for specific route

import { ClerkExpressWithAuth } from '@clerk/clerk-sdk-node';

const experimentalIsApiRoute = (url: URL) => url.pathname == '/public';
router.use(ClerkExpressWithAuth({ experimental_isApiRoute }));

// 3. @clerk/clerk-sdk-node with required authentication for all routes

import { ClerkExpressRequireAuth } from '@clerk/clerk-sdk-node';

router.use(ClerkExpressRequireAuth({ experimental_isApiRoute: true }));

[changeset-bot]

🦋 Changeset detected

Latest commit: 776c0a6

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 6 packages

Name	Type
@clerk/clerk-sdk-node	Minor
@clerk/backend	Minor
gatsby-plugin-clerk	Patch
@clerk/nextjs	Patch
@clerk/fastify	Patch
@clerk/remix	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[jit-ci]

✅ Great news! Jit hasn't found any security issues in your PR. Good Job! 🏆

[SokratisVidros]

@dimkl I think that we should make this more generic and call it ignoreInterstitial, which is either a boolean or a function boolean | ((url: URL | string) => string);. That way, we can cover more use cases such as assets, etc...

The apiRoutes option we added in @clerk/nextjs should also be able to leverage it.

[dimkl]

I didn't add the function in type since the url of the request is not available in the @clerk/backend package.
We can do that after the addition of the request parameter (see: #1393)

[SokratisVidros]

Correct. @nikosdouvlis how far are we from merging #1393 ?

[dimkl]

@SokratisVidros, i think we can continue with the boolean type and enhance it ( boolean | ((url: URL | string) => boolean);) when request parameter PR is merged.

[nikosdouvlis]

The authenticateRequest PR should be merged today, but lets do what @dimkl suggested.

Dimitri, can we add a JSDOC comment documenting what the prop does?

I'm not a fan of the ignoreIInterstitial name as it feels like an escape hatch and nothing a non-advanced Clerk user would understand. That being said, I don't have any better alternatives at the moment.

[dimkl]

@SokratisVidros , @nikosdouvlis comments have been addressed. PTAL.

[dimkl]

!snapshot

[clerk-cookie]

Hey @dimkl - the snapshot version command generated the following package versions:

Package	Version
@clerk/backend	0.24.0-snapshot.383c628
@clerk/chrome-extension	0.3.19-snapshot.383c628
@clerk/clerk-js	4.51.0
eslint-config-custom	0.3.0
@clerk/clerk-expo	0.18.10-snapshot.383c628
@clerk/fastify	0.5.6-snapshot.383c628
gatsby-plugin-clerk	4.3.19-snapshot.383c628
@clerk/localizations	1.22.0
@clerk/nextjs	4.21.13-snapshot.383c628
@clerk/clerk-react	4.21.1-snapshot.383c628
@clerk/remix	2.6.16-snapshot.383c628
@clerk/clerk-sdk-node	4.11.0-snapshot.383c628
@clerk/shared	0.19.1
@clerk/themes	1.7.5
@clerk/types	3.46.1

Tip: use the snippet copy button below to quickly install the required packages.

# @clerk/backend
npm i @clerk/backend@0.24.0-snapshot.383c628

# @clerk/chrome-extension
npm i @clerk/chrome-extension@0.3.19-snapshot.383c628

# @clerk/clerk-js
npm i @clerk/clerk-js@4.51.0

# eslint-config-custom
npm i eslint-config-custom@0.3.0

# @clerk/clerk-expo
npm i @clerk/clerk-expo@0.18.10-snapshot.383c628

# @clerk/fastify
npm i @clerk/fastify@0.5.6-snapshot.383c628

# gatsby-plugin-clerk
npm i gatsby-plugin-clerk@4.3.19-snapshot.383c628

# @clerk/localizations
npm i @clerk/localizations@1.22.0

# @clerk/nextjs
npm i @clerk/nextjs@4.21.13-snapshot.383c628

# @clerk/clerk-react
npm i @clerk/clerk-react@4.21.1-snapshot.383c628

# @clerk/remix
npm i @clerk/remix@2.6.16-snapshot.383c628

# @clerk/clerk-sdk-node
npm i @clerk/clerk-sdk-node@4.11.0-snapshot.383c628

# @clerk/shared
npm i @clerk/shared@0.19.1

# @clerk/themes
npm i @clerk/themes@1.7.5

# @clerk/types
npm i @clerk/types@3.46.1

[SokratisVidros]

❓ Why not experimental_ignoreInterstitial?

[dimkl]

I thought that frameworks using the @clerk/backend would have the option to define their API routes (that's why I have set it as experimental_isApiRoute ) and that we could use it internally to whatever we want eg:

• ignore interstitial
• avoid redirecting to sign-in (case of NextJS)
  Mainly I have used the same logic we have for NextJS and applied it to sdk-node.
  Should I rename it to experimental_ignoreInterstitial or not?
  cc: @nikosdouvlis

[nikosdouvlis]

Closing in favor of the solutions we're discussing at https://www.notion.so/clerkdev/Interstitial-public-Api-Pages-10369bee0edf47f3b410e45f2723f12c