From 72fb3203f9c42d8bfad9d3ff7160b45dd687ab5a Mon Sep 17 00:00:00 2001 From: Tamal Anwar Chowdhury Date: Mon, 15 Dec 2025 18:13:35 +0600 Subject: [PATCH 1/4] fix: getEnvironmentVariable cant be used --- .../understand-page-design.mdx | 74 +++++++++++++++++-- 1 file changed, 68 insertions(+), 6 deletions(-) diff --git a/src/content/docs/design/customize-with-code/understand-page-design.mdx b/src/content/docs/design/customize-with-code/understand-page-design.mdx index e4f9211fb..ad2f46412 100644 --- a/src/content/docs/design/customize-with-code/understand-page-design.mdx +++ b/src/content/docs/design/customize-with-code/understand-page-design.mdx @@ -323,20 +323,82 @@ The top level `context` key object contains information about the page itself, l ## Page settings -Sometimes additional information needs to be passed to Kinde from your page. You can use the page settings object for this. +Use the `pageSettings` object to configure what capabilities your custom UI page can access by enabling bindings. ```js -export const pageSettings = {}; +export const pageSettings = {} ``` -The main use case for this is when you want to make bindings available to your page, for example access to your Kinde environment variables. +The main use case for this is when you want to make bindings available to your page. For example, the `kinde.env` binding is required when calling the Kinde Management API via `createKindeAPI` (it's used internally for M2M authentication). However, this binding does not give you direct access to call `getEnvironmentVariable` in your page code. ```js export const pageSettings = { bindings: { - "kinde.env": {} + "kinde.env": {}, + "kinde.fetch": {}, + url: {} } -}; +} ``` -This allows you to have fine grained control over what your pages can access. +This allows you to have fine grained control over what your pages can access. See [Pages and the Kinde Management API](/design/customize-with-code/pages-and-kinde-api/) for more information about using bindings to make API calls. + +Note: If you don't need to call the Kinde Management API, you can leave pageSettings as an empty object {} or omit it entirely. + +## Environment Variables + +The `@kinde/infrastructure` package exports a `getEnvironmentVariable` method, but this method is not available in Custom UI pages, even if you import it. + +If you need to access environment variables in your Custom UI page, you have a few options: + +### Option 1: Pass data from the workflow handler to the page + +In your workflow handler, fetch the env var and return it in the `data` object: + + ```js + // In your workflow handler + import { getEnvironmentVariable } from "@kinde/infrastructure" + + export default async function handler(event) { + const publicUrl = getEnvironmentVariable("APP_PUBLIC_URL")?.value + return { + data: { + publicUrl, + }, + } + } + ``` + +Then access it in your Custom UI page via the `context` object. You can access the workflow data through `context.data`: + + ```js + // In your Custom UI page - Page function + export default async function Page(event) { + const { publicUrl } = event.context.data + // ... rest of your code + } + + // Or in your Layout component + const Layout = async ({request, context}) => { + const { publicUrl } = context.data + // ... rest of your code + } + ``` + +### Option 2: Hardcode or use a relative URL + +If `APP_PUBLIC_URL` is just for building URLs in the UI, consider using relative paths instead. + + ```js + // In your Custom UI page + const publicUrl = "/api/public-url" + ``` + +### Option 3: Fetch from an API + +Make an API call from your Custom UI page to retrieve the necessary configuration. This requires the `kinde.fetch` binding in your `pageSettings`. + + ```js + // In your Custom UI page + const publicUrl = await fetch("/api/public-url").then(res => res.json()).then(data => data.publicUrl); + ``` From 01e8c846e78030fa509a130349f6f87ccbe89377 Mon Sep 17 00:00:00 2001 From: Tamal Anwar Chowdhury Date: Mon, 15 Dec 2025 18:19:52 +0600 Subject: [PATCH 2/4] update meta and grammar --- .../design/customize-with-code/understand-page-design.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/design/customize-with-code/understand-page-design.mdx b/src/content/docs/design/customize-with-code/understand-page-design.mdx index ad2f46412..d5a4875f0 100644 --- a/src/content/docs/design/customize-with-code/understand-page-design.mdx +++ b/src/content/docs/design/customize-with-code/understand-page-design.mdx @@ -31,7 +31,7 @@ keywords: - kinde.json - route mapping - server rendering -updated: 2024-01-15 +updated: 2025-12-15 featured: false deprecated: false ai_summary: Comprehensive guide for understanding Kinde page customization including React templating, directory structure, route mapping, and server-rendered JavaScript implementation. @@ -341,7 +341,7 @@ export const pageSettings = { } ``` -This allows you to have fine grained control over what your pages can access. See [Pages and the Kinde Management API](/design/customize-with-code/pages-and-kinde-api/) for more information about using bindings to make API calls. +This allows you to have fine-grained control over what your pages can access. See [Pages and the Kinde Management API](/design/customize-with-code/pages-and-kinde-api/) for more information about using bindings to make API calls. Note: If you don't need to call the Kinde Management API, you can leave pageSettings as an empty object {} or omit it entirely. From 82834ad1e6de8e0094442bd47e0b34508b225d32 Mon Sep 17 00:00:00 2001 From: Tamal Anwar Chowdhury Date: Thu, 18 Dec 2025 17:54:51 +0600 Subject: [PATCH 3/4] add page settings clarification --- .../understand-page-design.mdx | 32 +++++++------------ 1 file changed, 11 insertions(+), 21 deletions(-) diff --git a/src/content/docs/design/customize-with-code/understand-page-design.mdx b/src/content/docs/design/customize-with-code/understand-page-design.mdx index d5a4875f0..2eb1a3acf 100644 --- a/src/content/docs/design/customize-with-code/understand-page-design.mdx +++ b/src/content/docs/design/customize-with-code/understand-page-design.mdx @@ -189,7 +189,7 @@ myApp/ └── kinde.json ``` -## Kinde.json +## `kinde.json` file The `kinde.json` file defines the config for all custom code in Kinde, including workflows and custom pages. A typical config file will look as follows: @@ -321,29 +321,19 @@ The top level `context` key object contains information about the page itself, l - `description` the page description - `logoAlt` the alt text for your company logo -## Page settings +## `pageSettings` object -Use the `pageSettings` object to configure what capabilities your custom UI page can access by enabling bindings. +The `pageSettings` object is required when you need to enable bindings that give your page access to additional Kinde features, such as environment variables or the fetch API. Without declaring these bindings in `pageSettings`, these features won't be available in your page code. -```js -export const pageSettings = {} -``` - -The main use case for this is when you want to make bindings available to your page. For example, the `kinde.env` binding is required when calling the Kinde Management API via `createKindeAPI` (it's used internally for M2M authentication). However, this binding does not give you direct access to call `getEnvironmentVariable` in your page code. - -```js -export const pageSettings = { - bindings: { - "kinde.env": {}, - "kinde.fetch": {}, - url: {} - } -} -``` - -This allows you to have fine-grained control over what your pages can access. See [Pages and the Kinde Management API](/design/customize-with-code/pages-and-kinde-api/) for more information about using bindings to make API calls. + ```js + export const pageSettings = { + bindings: { + "kinde.env": {} + } + } + ``` -Note: If you don't need to call the Kinde Management API, you can leave pageSettings as an empty object {} or omit it entirely. +Bindings are explicitly opted-in for performance reasons. By declaring only the bindings you need, you tell Kinde's runtime which internal features to initialize, avoiding unnecessary computation and keeping your page render as fast as possible. ## Environment Variables From 4c81cccc437bafea29cb517e825f0279401a99c0 Mon Sep 17 00:00:00 2001 From: Tamal Anwar Chowdhury Date: Thu, 18 Dec 2025 18:25:18 +0600 Subject: [PATCH 4/4] update the doc with env variable with code example and clarification --- .../understand-page-design.mdx | 85 +++++++++---------- 1 file changed, 39 insertions(+), 46 deletions(-) diff --git a/src/content/docs/design/customize-with-code/understand-page-design.mdx b/src/content/docs/design/customize-with-code/understand-page-design.mdx index 2eb1a3acf..d579566ae 100644 --- a/src/content/docs/design/customize-with-code/understand-page-design.mdx +++ b/src/content/docs/design/customize-with-code/understand-page-design.mdx @@ -333,62 +333,55 @@ The `pageSettings` object is required when you need to enable bindings that give } ``` -Bindings are explicitly opted-in for performance reasons. By declaring only the bindings you need, you tell Kinde's runtime which internal features to initialize, avoiding unnecessary computation and keeping your page render as fast as possible. + -## Environment Variables +## How to access environment variables in your page -The `@kinde/infrastructure` package exports a `getEnvironmentVariable` method, but this method is not available in Custom UI pages, even if you import it. +You can access environment variables within your custom UI pages using the `getEnvironmentVariable` method. To enable this functionality, you must add the `pageSettings` object with the environment binding in all of your custom pages. -If you need to access environment variables in your Custom UI page, you have a few options: +Follow these steps: -### Option 1: Pass data from the workflow handler to the page +1. Set up your environment variables in Kinde > **Environment** > **Settings** > **Env variables** +2. Add the `pageSettings` object with the `kinde.env` binding to your page file +3. Import the `getEnvironmentVariable` method from `@kinde/infrastructure` +4. Access the environment variable within your Page component -In your workflow handler, fetch the env var and return it in the `data` object: +Example: - ```js - // In your workflow handler - import { getEnvironmentVariable } from "@kinde/infrastructure" + ```tsx + "use server"; + import { type KindePageEvent, getEnvironmentVariable } from "@kinde/infrastructure"; + import React from "react"; + import { renderToString } from "react-dom/server.browser"; - export default async function handler(event) { - const publicUrl = getEnvironmentVariable("APP_PUBLIC_URL")?.value - return { - data: { - publicUrl, - }, - } - } - ``` - -Then access it in your Custom UI page via the `context` object. You can access the workflow data through `context.data`: - - ```js - // In your Custom UI page - Page function - export default async function Page(event) { - const { publicUrl } = event.context.data - // ... rest of your code - } - - // Or in your Layout component - const Layout = async ({request, context}) => { - const { publicUrl } = context.data - // ... rest of your code - } - ``` + const DefaultPage: React.FC = ({ context, request }) => { + // Access environment variables inside your component + const publicUrl = getEnvironmentVariable("APP_PUBLIC_URL")?.value; -### Option 2: Hardcode or use a relative URL + return ( +
+

Public URL: {publicUrl}

+
+ ); + } -If `APP_PUBLIC_URL` is just for building URLs in the UI, consider using relative paths instead. + export default async function Page(event: KindePageEvent): Promise { + const page = await DefaultPage(event); + return renderToString(page); + } - ```js - // In your Custom UI page - const publicUrl = "/api/public-url" - ``` + // Required: Add pageSettings with kinde.env binding to enable environment variable access + export const pageSettings = { + bindings: { + "kinde.env": {} + } + } + ``` -### Option 3: Fetch from an API + \ No newline at end of file