DEV Community: Moya Richards

Build a VS Code Webview with Vue, Vite, Tailwind CSS, and VS Code-Themed Components

Moya Richards — Wed, 13 May 2026 14:42:06 +0000

This tutorial shows how to create a VS Code extension that opens a custom webview powered by:

Vue for the webview UI
Vite for fast frontend builds. Supports Vue 3.4
Tailwind CSS for layout and custom styling
VS Code CSS theme variables for native-looking controls
VS Code Webview API for rendering the UI inside VS Code

1. Prerequisites

Install Node.js and npm first.

Then install the VS Code extension generator:

npm install --global yo generator-code

You should also have VS Code installed.

2. Create the VS Code Extension

Run:

yo code

Choose these options:

✔ What type of extension do you want to create? New Extension (TypeScript)
✔ What's the name of your extension? vue-webview-vite
✔ What's the identifier of your extension? vue-webview-vite
✔ What's the description of your extension? webview
✔ Initialize a git repository? Yes
✔ Which bundler to use? unbundled
✔ Which package manager to use? npm

This creates the extension shell where the important files are:

vue-webview-vite/
  package.json
  src/
    extension.ts
  tsconfig.json

Update the extension root tsconfig.json so the extension compiler only reads files from src/ and does not accidentally compile the Vite Vue app inside webview-ui.

{
  "compilerOptions": {
    "module": "Node16",
    "target": "ES2022",
    "outDir": "out",
    "lib": ["ES2022"],
    "sourceMap": true,
    "rootDir": "src",
    "strict": true
  },
  "include": ["src/**/*.ts"],
  "exclude": ["node_modules", "webview-ui", "out"]
}

The important part is:

"include": ["src/**/*.ts"],
"exclude": ["node_modules", "webview-ui", "out"]

Without include, TypeScript may use the default pattern **/*, which can accidentally compile the Vite Vue app inside webview-ui.

3. Run the Extension for the First Time

Open the generated extension in VS Code and click on src/extension.ts.

Press:

F5

This starts the extension in a new window called the Extension Development Host.

In that new window:

Open the Command Palette:
- Windows: Ctrl + Shift + P
- macOS: Cmd + Shift + P
Run:

Hello World

You should see the default extension message:

Hello World from vue-webview-vite!

This confirms that the extension host works before adding Vue.

4. Add a Vue App with Vite

From the extension root, run the command below to create a Vue + TypeScript app inside a folder named webview-ui:

npm create vite@latest webview-ui

Choose these options:

✔ Select a framework? Vue
✔ Select a variant? TypeScript

Install the webview app dependencies:

cd webview-ui
npm install

Your project should now look like this:

vue-webview-vite/
  src/
    extension.ts
  webview-ui/
    index.html
    package.json
    src/
      App.vue
      main.ts
      style.css
    vite.config.ts

5. Install Tailwind CSS for Vite

Make sure you are inside webview-ui:

cd webview-ui

Install Tailwind using the Vite plugin:

npm install tailwindcss @tailwindcss/vite

Update webview-ui/vite.config.ts:

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import tailwindcss from "@tailwindcss/vite";

export default defineConfig({
  plugins: [vue(), tailwindcss()],
  build: {
    outDir: "dist",
    emptyOutDir: true,
    rollupOptions: {
      output: {
        entryFileNames: "assets/[name].js",
        chunkFileNames: "assets/[name].js",
        assetFileNames: "assets/[name].[ext]",
      },
    },
  },
});

Update webview-ui/src/style.css:

@import "tailwindcss";

:root {
  font-family: var(--vscode-font-family);
  color: var(--vscode-foreground);
  background: var(--vscode-editor-background);
}

body {
  margin: 0;
  min-width: 320px;
  min-height: 100vh;
  background: var(--vscode-editor-background);
  color: var(--vscode-foreground);
}

button,
input,
textarea,
select {
  font-family: inherit;
}

This setup keeps Tailwind available while still respecting VS Code theme variables.

6. Create VS Code-Themed Vue Components

Build regular Vue components.
Style them with Tailwind.
Use VS Code CSS variables such as --vscode-button-background, --vscode-input-background, and --vscode-panel-border.

Create webview-ui/src/components/VSCodeButton.vue:

<script setup lang="ts">
defineProps<{
  variant?: "primary" | "secondary";
}>();
</script>

<template>
  <button
    :class="[
      'rounded px-3 py-1.5 text-sm font-medium focus:outline focus:outline-1 focus:outline-[var(--vscode-focusBorder)]',
      variant === 'secondary'
        ? 'bg-[var(--vscode-button-secondaryBackground)] text-[var(--vscode-button-secondaryForeground)] hover:bg-[var(--vscode-button-secondaryHoverBackground)]'
        : 'bg-[var(--vscode-button-background)] text-[var(--vscode-button-foreground)] hover:bg-[var(--vscode-button-hoverBackground)]',
    ]"
  >
    <slot />
  </button>
</template>

Create webview-ui/src/components/VSCodeTextField.vue:

<script setup lang="ts">
const fieldValue = defineModel<string>({ required: true });

defineProps<{
  placeholder?: string;
}>();
</script>

<template>
  <input
    v-model="fieldValue"
    :placeholder="placeholder"
    class="w-full rounded border border-[var(--vscode-input-border)] bg-[var(--vscode-input-background)] px-3 py-2 text-sm text-[var(--vscode-input-foreground)] placeholder:text-[var(--vscode-input-placeholderForeground)] focus:outline focus:outline-1 focus:outline-[var(--vscode-focusBorder)]"
  />
</template>

Create webview-ui/src/components/VSCodeTextArea.vue:

<script setup lang="ts">
const textValue = defineModel<string>({ required: true });

defineProps<{
  placeholder?: string;
}>();
</script>

<template>
  <textarea
    v-model="textValue"
    :placeholder="placeholder"
    class="min-h-24 w-full rounded border border-[var(--vscode-input-border)] bg-[var(--vscode-input-background)] px-3 py-2 text-sm text-[var(--vscode-input-foreground)] placeholder:text-[var(--vscode-input-placeholderForeground)] focus:outline focus:outline-1 focus:outline-[var(--vscode-focusBorder)]"
  />
</template>

Create webview-ui/src/components/VSCodeCard.vue:

<template>
  <section
    class="rounded-xl border border-[var(--vscode-panel-border)] bg-[var(--vscode-sideBar-background)] p-5 shadow-sm"
  >
    <slot />
  </section>
</template>

The UI combines Tailwind utility classes with VS Code CSS variables such as:

var(--vscode-editor-background)
var(--vscode-foreground)
var(--vscode-descriptionForeground)
var(--vscode-panel-border)
var(--vscode-button-background)
var(--vscode-input-background)

That keeps the webview aligned with the active VS Code theme.

7. Create the Vue Webview UI with VS Code API Messaging

Create the Vue webview UI with VS Code message passing included from the start.

A webview runs like a small web app, but it cannot directly call the VS Code extension API. Instead, the Vue app sends messages to the extension, and the extension runs VS Code APIs on its behalf.

The flow looks like this:

Vue button click
  → webview postMessage
  → extension receives message
  → extension runs VS Code API
  → extension sends response back to Vue
  → Vue updates the UI

Create the VS Code API wrapper

Create webview-ui/src/api/vscode-api.ts:

export type WebviewMessage =
  | {
      type: "saveSettings";
      payload: {
        projectName: string;
        format: string;
        notes: string;
      };
    }
  | {
      type: "showInfo";
      payload: {
        message: string;
      };
    };

let vscodeApi: VSCodeApi | undefined;

function getVsCodeApi() {
  if (vscodeApi) {
    return vscodeApi;
  }

  if (typeof acquireVsCodeApi === "function") {
    vscodeApi = acquireVsCodeApi();
    return vscodeApi;
  }

  return undefined;
}

export function postMessage(message: WebviewMessage) {
  const vscode = getVsCodeApi();

  if (!vscode) {
    console.log("VS Code API is not available. Message was not sent:", message);
    return;
  }

  vscode.postMessage(message);
}

export function getVsCodeState<T>() {
  const vscode = getVsCodeApi();
  return vscode?.getState<T>();
}

export function setVsCodeState<T>(state: T) {
  const vscode = getVsCodeApi();
  vscode?.setState(state);
}

This wrapper is the only place where the Vue app should call acquireVsCodeApi().

The wrapper calls acquireVsCodeApi() lazily, only when the app needs to communicate with VS Code. This prevents the app from crashing during Vite browser development or testing.

Add webview API types for the wrapper

Create webview-ui/src/vscode.d.ts:

type VSCodeApi = {
  postMessage: (message: unknown) => void;
  getState: <T = unknown>() => T | undefined;
  setState: <T = unknown>(state: T) => void;
};

declare function acquireVsCodeApi(): VSCodeApi;

VS Code provides acquireVsCodeApi() inside the webview, but TypeScript does not know about it by default. This file adds the type information needed by webview-ui/src/api/vscode-api.ts.

The wrapper checks typeof acquireVsCodeApi === "function" because the function only exists inside VS Code, not when previewing the Vue app in a normal browser.

Create `webview-ui/src/components/Webview.vue`

Create webview-ui/src/components/Webview.vue:

<script setup lang="ts">
import { onMounted, onUnmounted, ref, watch } from "vue";
import VSCodeButton from "./VSCodeButton.vue";
import VSCodeCard from "./VSCodeCard.vue";
import VSCodeTextArea from "./VSCodeTextArea.vue";
import VSCodeTextField from "./VSCodeTextField.vue";
import { getVsCodeState, postMessage, setVsCodeState } from "../api/vscode-api";

type AppState = {
  projectName: string;
  format: string;
  notes: string;
};

type ExtensionMessage =
  | {
      type: "settingsSaved";
      payload: {
        savedAt: string;
      };
    }
  | {
      type: "fromExtension";
      payload: {
        message: string;
      };
    };

const defaultState: AppState = {
  projectName: "Jupytext Pair Helper",
  format: "ipynb,py:percent",
  notes: "",
};

const savedState = getVsCodeState<AppState>();

const projectName = ref(savedState?.projectName ?? defaultState.projectName);
const format = ref(savedState?.format ?? defaultState.format);
const notes = ref(savedState?.notes ?? defaultState.notes);
const status = ref("Ready");

watch(
  [projectName, format, notes],
  () => {
    setVsCodeState({
      projectName: projectName.value,
      format: format.value,
      notes: notes.value,
    });
  },
  { immediate: true },
);

function saveSettings() {
  postMessage({
    type: "saveSettings",
    payload: {
      projectName: projectName.value,
      format: format.value,
      notes: notes.value,
    },
  });
}

function showInfoMessage() {
  postMessage({
    type: "showInfo",
    payload: {
      message: `Current project: ${projectName.value}`,
    },
  });
}

function resetSettings() {
  projectName.value = defaultState.projectName;
  format.value = defaultState.format;
  notes.value = defaultState.notes;
  status.value =
    "Reset locally. Click Save settings to send the update to VS Code.";
}

function handleMessage(event: MessageEvent<ExtensionMessage>) {
  const message = event.data;

  switch (message.type) {
    case "settingsSaved":
      status.value = `Settings saved at ${message.payload.savedAt}`;
      break;
    case "fromExtension":
      status.value = message.payload.message;
      break;
  }
}

onMounted(() => {
  window.addEventListener("message", handleMessage);
});

onUnmounted(() => {
  window.removeEventListener("message", handleMessage);
});
</script>

<template>
  <main class="min-h-screen p-5">
    <section class="mx-auto grid max-w-4xl gap-5">
      <VSCodeCard>
        <p
          class="text-xs uppercase tracking-wide text-[var(--vscode-descriptionForeground)]"
        >
          VS Code Webview Tutorial
        </p>
        <h1 class="mt-2 text-2xl font-semibold text-[var(--vscode-foreground)]">
          Vue + Vite + Tailwind + VS Code Message Passing
        </h1>
        <p
          class="mt-2 max-w-2xl text-sm leading-6 text-[var(--vscode-descriptionForeground)]"
        >
          This webview uses Vue for state, Tailwind for layout, and VS Code
          message passing to communicate with the extension.
        </p>
      </VSCodeCard>

      <div class="grid gap-5 md:grid-cols-2">
        <VSCodeCard>
          <h2 class="text-lg font-medium">Settings</h2>

          <div class="mt-4 grid gap-4">
            <label class="grid gap-1 text-sm">
              <span class="text-[var(--vscode-descriptionForeground)]"
                >Project name</span
              >
              <VSCodeTextField v-model="projectName" />
            </label>

            <label class="grid gap-1 text-sm">
              <span class="text-[var(--vscode-descriptionForeground)]"
                >Pairing format</span
              >
              <select
                v-model="format"
                class="w-full rounded border border-[var(--vscode-dropdown-border)] bg-[var(--vscode-dropdown-background)] px-3 py-2 text-sm text-[var(--vscode-dropdown-foreground)] focus:outline focus:outline-1 focus:outline-[var(--vscode-focusBorder)]"
              >
                <option value="ipynb,py:percent">Python percent pair</option>
                <option value="ipynb,md:myst">Markdown MyST pair</option>
                <option value="ipynb,md,pct.py:percent">
                  Notebook + Markdown + percent script
                </option>
              </select>
            </label>

            <label class="grid gap-1 text-sm">
              <span class="text-[var(--vscode-descriptionForeground)]"
                >Notes</span
              >
              <VSCodeTextArea
                v-model="notes"
                placeholder="Notes about the selected pairing format..."
              />
            </label>

            <div class="flex flex-wrap gap-2">
              <VSCodeButton @click="saveSettings">Save settings</VSCodeButton>
              <VSCodeButton @click="showInfoMessage"
                >Show VS Code message</VSCodeButton
              >
              <VSCodeButton variant="secondary" @click="resetSettings"
                >Reset</VSCodeButton
              >
            </div>
          </div>
        </VSCodeCard>

        <VSCodeCard>
          <h2 class="text-lg font-medium">Preview</h2>

          <div class="mt-4 grid gap-4">
            <div
              class="rounded-lg border border-[var(--vscode-panel-border)] p-4"
            >
              <p class="text-sm text-[var(--vscode-descriptionForeground)]">
                Project
              </p>
              <h3 class="mt-1 text-lg font-medium">{{ projectName }}</h3>
            </div>

            <div
              class="rounded-lg border border-[var(--vscode-panel-border)] p-4"
            >
              <p class="text-sm text-[var(--vscode-descriptionForeground)]">
                Selected Jupytext format
              </p>
              <code
                class="mt-2 block rounded bg-[var(--vscode-textCodeBlock-background)] p-3"
              >
                {{ format }}
              </code>
            </div>

            <div
              class="rounded-lg border border-[var(--vscode-panel-border)] p-4"
            >
              <p class="text-sm text-[var(--vscode-descriptionForeground)]">
                Status
              </p>
              <p class="mt-1 text-sm">{{ status }}</p>
            </div>
          </div>
        </VSCodeCard>
      </div>
    </section>
  </main>
</template>

How the interaction works

The Vue webview sends this message when the user clicks Save settings:

postMessage({
  type: "saveSettings",
  payload: {
    projectName: projectName.value,
    format: format.value,
    notes: notes.value,
  },
});

The extension receives that message, runs extension-side logic, and sends a response back to Vue.

The Vue webview receives extension messages here:

window.addEventListener("message", handleMessage);

8. Make `App.vue` Render `Webview.vue`

Keep App.vue small. Its job is to load the main webview component.

Create/Edit webview-ui/src/App.vue:

<script setup lang="ts">
import Webview from "./components/Webview.vue";
</script>

<template>
  <Webview />
</template>

This keeps the main webview logic inside components/Webview.vue, while App.vue stays as the Vue app entry component.

9. Build the Vue App

From inside webview-ui, run:

npm run build

A current Vite Vue TypeScript project usually uses this build script in webview-ui/package.json:

{
  "scripts": {
    "dev": "vite",
    "build": "vue-tsc -b && vite build",
    "preview": "vite preview"
  }
}

vue-tsc -b type-checks Vue single-file components, and vite build creates the webview bundle.

Vite creates:

webview-ui/dist/
  index.html
  assets/
    index.js
    index.css

The extension will load these built files into the webview.

10. Add the Webview Command to `package.json`

Open the extension root package.json.

Update contributes.commands:

{
  "contributes": {
    "commands": [
      {
        "command": "vue-webview-vite.openPanel",
        "title": "Open Vue Webview"
      }
    ]
  }
}

Make sure the command name matches the command registered in extension.ts.

11. Create the Webview Panel in `extension.ts`

Replace src/extension.ts with:

import * as vscode from "vscode";

type WebviewMessage =
  | {
      type: "saveSettings";
      payload: {
        projectName: string;
        format: string;
        notes: string;
      };
    }
  | {
      type: "showInfo";
      payload: {
        message: string;
      };
    };

export function activate(context: vscode.ExtensionContext) {
  const disposable = vscode.commands.registerCommand(
    "vue-webview-vite.openPanel",
    () => {
      const panel = vscode.window.createWebviewPanel(
        "vueWebviewVite",
        "Vue Webview",
        vscode.ViewColumn.One,
        {
          enableScripts: true,
          localResourceRoots: [
            vscode.Uri.joinPath(context.extensionUri, "webview-ui", "dist"),
          ],
        },
      );

      panel.webview.html = getWebviewHtml(panel.webview, context.extensionUri);

      panel.webview.onDidReceiveMessage(
        async (message: WebviewMessage) => {
          switch (message.type) {
            case "saveSettings": {
              await context.globalState.update(
                "vueWebviewVite.settings",
                message.payload,
              );

              vscode.window.showInformationMessage(
                `Saved settings for ${message.payload.projectName}`,
              );

              panel.webview.postMessage({
                type: "settingsSaved",
                payload: {
                  savedAt: new Date().toLocaleTimeString(),
                },
              });

              break;
            }

            case "showInfo": {
              vscode.window.showInformationMessage(message.payload.message);

              panel.webview.postMessage({
                type: "fromExtension",
                payload: {
                  message:
                    "VS Code received the message and showed a notification.",
                },
              });

              break;
            }
          }
        },
        undefined,
        context.subscriptions,
      );
    },
  );

  context.subscriptions.push(disposable);
}

function getWebviewHtml(webview: vscode.Webview, extensionUri: vscode.Uri) {
  const scriptUri = webview.asWebviewUri(
    vscode.Uri.joinPath(
      extensionUri,
      "webview-ui",
      "dist",
      "assets",
      "index.js",
    ),
  );

  const styleUri = webview.asWebviewUri(
    vscode.Uri.joinPath(
      extensionUri,
      "webview-ui",
      "dist",
      "assets",
      "index.css",
    ),
  );

  const nonce = getNonce();

  return /* html */ `
    <!DOCTYPE html>
    <html lang="en">
      <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />

        <meta
          http-equiv="Content-Security-Policy"
          content="default-src 'none'; img-src ${webview.cspSource} https:; style-src ${webview.cspSource} 'unsafe-inline'; script-src 'nonce-${nonce}';"
        />

        <link rel="stylesheet" href="${styleUri}" />
        <title>Vue Webview</title>
      </head>
      <body>
        <div id="app"></div>
        <script type="module" nonce="${nonce}" src="${scriptUri}"></script>
      </body>
    </html>
  `;
}

function getNonce() {
  let text = "";
  const possible =
    "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";

  for (let i = 0; i < 32; i++) {
    text += possible.charAt(Math.floor(Math.random() * possible.length));
  }

  return text;
}

export function deactivate() {}

Important details:

enableScripts: true allows the Vue bundle to run.
localResourceRoots allows the webview to read files from webview-ui/dist.
webview.asWebviewUri(...) converts extension file paths into safe webview URLs.
context.extensionUri points to the extension root folder, not the out/ folder.
The compiled extension runs from out/extension.js, but it can still reference webview-ui/dist/assets/index.js relative to the extension root.
The CSP uses a nonce so only the intended script can run.

12. Run Both Development Watchers

From your terminal, make sure you are in the extension root folder:

cd vue-webview-vite

For development, run the extension's TypeScript watcher and the Vite webview watcher at the same time.

You need both because they build different parts of the project:

Extension watcher → compiles src/extension.ts into out/extension.js
Webview watcher   → builds Vue/Tailwind files into webview-ui/dist/

Use concurrently because both watcher commands are long-running processes.

From the extension root, install it:

npm install -D concurrently

Add these scripts to the extension root package.json:

{
  "scripts": {
    "watch": "tsc -watch -p ./",
    "watch:webview": "npm --prefix webview-ui run build -- --watch",
    "dev": "concurrently \"npm run watch\" \"npm run watch:webview\""
  }
}

Now start both watchers from the extension root:

npm run dev

This keeps both outputs updated while you work:

out/extension.js
webview-ui/dist/assets/index.js
webview-ui/dist/assets/index.css

13. Start and Reload the Extension

To start the extension:

Open the extension project in VS Code.
Press F5.
A new Extension Development Host window opens.
Open the Command Palette.
Run:

Open Vue Webview

The Vue webview should appear.

Reloading after changes

There are two common reload flows.

If you changed Vue code

Keep npm run dev running from the extension root.
Close the webview panel.
Run Open Vue Webview again.

Usually you do not need to restart the full Extension Development Host for Vue-only changes.

If you changed extension code

If you changed src/extension.ts or package.json:

Go to the Extension Development Host window.
Press:

Ctrl + R

On macOS, use:

Cmd + R

This reloads the Extension Development Host.

Then run:

Open Vue Webview

again from the Command Palette.

14. Production Build

Before packaging or publishing the extension, build both parts:

npm run compile
npm --prefix webview-ui run build

You should commit or package the built webview assets depending on your publishing workflow.

15. Quick Checks

Before running the extension, confirm these files exist:

out/extension.js
webview-ui/dist/assets/index.js
webview-ui/dist/assets/index.css

Also confirm the command ID matches in both places:

package.json → contributes.commands[].command
src/extension.ts → vscode.commands.registerCommand(...)

If the webview is blank, open VS Code Developer Tools with:

Developer: Toggle Developer Tools

16. Final Folder Structure

vue-webview-vite/
  package.json
  tsconfig.json
  src/
    extension.ts
  out/
    extension.js
    extension.js.map
  webview-ui/
    package.json
    vite.config.ts
    index.html
    src/
      App.vue
      main.ts
      style.css
      vscode.d.ts
      api/
        vscode-api.ts
      components/
        Webview.vue
        VSCodeButton.vue
        VSCodeCard.vue
        VSCodeTextArea.vue
        VSCodeTextField.vue
    dist/
      assets/
        index.js
        index.css

Summary

You now have a VS Code extension that:

Registers a command in the Command Palette
Opens a custom webview panel
Loads a Vue app built by Vite
Uses Tailwind CSS for layout and styling
Uses small reusable Vue components styled with VS Code theme variables
Sends messages from the Vue webview to the VS Code extension
Sends messages from the extension back to the Vue webview
Supports a practical reload workflow during development

The key development loop is:

npm run dev

Then:

F5 → Open Vue Webview → edit Vue → close/reopen panel → edit extension → Ctrl/Cmd + R

Source Code

https://github.com/moyarich/vue-webview-vite

Build a VS Code Webview with React, Vite, Tailwind CSS, and VS Code-Themed Components

Moya Richards — Wed, 13 May 2026 13:29:52 +0000

This tutorial shows how to create a VS Code extension that opens a custom webview powered by:

React for the webview UI
Vite for fast frontend builds
Tailwind CSS for layout and custom styling
VS Code CSS theme variables for native-looking controls
VS Code Webview API for rendering the UI inside VS Code

1. Prerequisites

Install Node.js and npm first.

Then install the VS Code extension generator:

npm install --global yo generator-code

You should also have VS Code installed.

2. Create the VS Code Extension

Run:

yo code

Choose these options:

✔ What type of extension do you want to create? New Extension (TypeScript)
✔ What's the name of your extension? react-webview-vite
✔ What's the identifier of your extension? react-webview-vite
✔ What's the description of your extension? webview
✔ Initialize a git repository? Yes
✔ Which bundler to use? unbundled
✔ Which package manager to use? npm

This creates the extension shell where the important files are:

react-webview-vite/
  package.json
  src/
    extension.ts
  tsconfig.json

Update the extension root tsconfig.json so the extension compiler only reads files from src/ and does not accidentally compile the Vite React app inside webview-ui.

{
  "compilerOptions": {
    "module": "Node16",
    "target": "ES2022",
    "outDir": "out",
    "lib": ["ES2022"],
    "sourceMap": true,
    "rootDir": "src",
    "strict": true
  },
  "exclude": ["webview-ui"]
}

3. Run the Extension for the First Time

Open the generated extension in VS Code. click on src/extension.ts

Press:

F5

This starts the extension in a new window called the Extension Development Host.

In that new window:

Open the Command Palette:

Windows: Ctrl + Shift + P
macOS: Cmd + Shift + P
1. Run: Hello World

You should see the extension message: Hello World from react-webview-vite!

This confirms that the extension host works before adding React.

4. Add a React App with Vite

From the extension root, run the command below to create a React + TypeScript app inside a folder named webview-ui:

npm create vite@latest webview-ui

Choose these options:

✔ Select a framework? React
✔ Select a variant? TypeScript

Your project should now look like this:

react-webview-vite/
  src/
    extension.ts
  webview-ui/
    index.html
    package.json
    src/
      App.tsx
      main.tsx
      index.css
    vite.config.ts

5. Install Tailwind CSS for Vite

To install dependencies:

cd webview-ui

Inside webview-ui, install Tailwind using the Vite plugin:

npm install tailwindcss @tailwindcss/vite

Update webview-ui/vite.config.ts:

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import tailwindcss from "@tailwindcss/vite";

export default defineConfig({
  plugins: [react(), tailwindcss()],
  build: {
    outDir: "dist",
    emptyOutDir: true,
    rollupOptions: {
      output: {
        entryFileNames: "assets/[name].js",
        chunkFileNames: "assets/[name].js",
        assetFileNames: "assets/[name].[ext]",
      },
    },
  },
});

Update webview-ui/src/index.css:

@import "tailwindcss";

:root {
  font-family: var(--vscode-font-family);
  color: var(--vscode-foreground);
  background: var(--vscode-editor-background);
}

body {
  margin: 0;
  min-width: 320px;
  min-height: 100vh;
  background: var(--vscode-editor-background);
  color: var(--vscode-foreground);
}

button,
input,
textarea,
select {
  font-family: inherit;
}

This setup keeps Tailwind available while still respecting VS Code theme variables.

6. Create VS Code-Themed React Components

Build regular React components.
Style them with Tailwind.
Optionally use headless libraries like Radix UI if you need advanced accessible primitives such as dialogs, popovers, tabs, or dropdown menus.

Create webview-ui/src/components/vscode-ui.tsx:

import type {
  ButtonHTMLAttributes,
  InputHTMLAttributes,
  TextareaHTMLAttributes,
} from "react";

export function VSCodeButton({
  className = "",
  ...props
}: ButtonHTMLAttributes<HTMLButtonElement>) {
  return (
    <button
      className={`rounded px-3 py-1.5 text-sm font-medium text-[var(--vscode-button-foreground)] bg-[var(--vscode-button-background)] hover:bg-[var(--vscode-button-hoverBackground)] focus:outline focus:outline-1 focus:outline-[var(--vscode-focusBorder)] ${className}`}
      {...props}
    />
  );
}

export function VSCodeSecondaryButton({
  className = "",
  ...props
}: ButtonHTMLAttributes<HTMLButtonElement>) {
  return (
    <button
      className={`rounded px-3 py-1.5 text-sm font-medium text-[var(--vscode-button-secondaryForeground)] bg-[var(--vscode-button-secondaryBackground)] hover:bg-[var(--vscode-button-secondaryHoverBackground)] focus:outline focus:outline-1 focus:outline-[var(--vscode-focusBorder)] ${className}`}
      {...props}
    />
  );
}

export function VSCodeTextField({
  className = "",
  ...props
}: InputHTMLAttributes<HTMLInputElement>) {
  return (
    <input
      className={`w-full rounded border border-[var(--vscode-input-border)] bg-[var(--vscode-input-background)] px-3 py-2 text-sm text-[var(--vscode-input-foreground)] placeholder:text-[var(--vscode-input-placeholderForeground)] focus:outline focus:outline-1 focus:outline-[var(--vscode-focusBorder)] ${className}`}
      {...props}
    />
  );
}

export function VSCodeTextArea({
  className = "",
  ...props
}: TextareaHTMLAttributes<HTMLTextAreaElement>) {
  return (
    <textarea
      className={`min-h-24 w-full rounded border border-[var(--vscode-input-border)] bg-[var(--vscode-input-background)] px-3 py-2 text-sm text-[var(--vscode-input-foreground)] placeholder:text-[var(--vscode-input-placeholderForeground)] focus:outline focus:outline-1 focus:outline-[var(--vscode-focusBorder)] ${className}`}
      {...props}
    />
  );
}

export function VSCodeCard({
  className = "",
  children,
}: {
  className?: string;
  children: React.ReactNode;
}) {
  return (
    <section
      className={`rounded-xl border border-[var(--vscode-panel-border)] bg-[var(--vscode-sideBar-background)] p-5 shadow-sm ${className}`}
    >
      {children}
    </section>
  );
}

The UI intentionally combines Tailwind utility classes with VS Code CSS variables such as:

var(--vscode-editor-background)
var(--vscode-foreground)
var(--vscode-descriptionForeground)
var(--vscode-panel-border)
var(--vscode-button-background)
var(--vscode-input-background)

That keeps the webview aligned with the active VS Code theme.

7. Create the React Webview UI with VS Code API Messaging

Create the React webview UI with VS Code message passing included from the start.

A webview runs like a small web app, but it cannot directly call the VS Code extension API. Instead, the React app sends messages to the extension, and the extension runs VS Code APIs on its behalf.

The flow looks like this:

React button click
  → webview postMessage
  → extension receives message
  → extension runs VS Code API
  → extension sends response back to React
  → React updates the UI

Create the VS Code API wrapper

Create webview-ui/src/api/vscode-api.ts:

export type WebviewMessage =
  | {
      type: "saveSettings";
      payload: {
        projectName: string;
        format: string;
        notes: string;
      };
    }
  | {
      type: "showInfo";
      payload: {
        message: string;
      };
    };

let vscodeApi: VSCodeApi | undefined;

function getVsCodeApi() {
  if (vscodeApi) {
    return vscodeApi;
  }

  if (typeof acquireVsCodeApi === "function") {
    vscodeApi = acquireVsCodeApi();
    return vscodeApi;
  }

  return undefined;
}

export function postMessage(message: WebviewMessage) {
  const vscode = getVsCodeApi();

  if (!vscode) {
    console.log("VS Code API is not available. Message was not sent:", message);
    return;
  }

  vscode.postMessage(message);
}

export function getVsCodeState<T>() {
  const vscode = getVsCodeApi();
  return vscode?.getState<T>();
}

export function setVsCodeState<T>(state: T) {
  const vscode = getVsCodeApi();
  vscode?.setState(state);
}

This wrapper is the only place where the React app should call acquireVsCodeApi().

The wrapper calls acquireVsCodeApi() lazily, only when the app needs to communicate with VS Code. This prevents the app from crashing during Vite browser development or testing.

Add webview API types for the wrapper

Create webview-ui/src/vscode.d.ts:

type VSCodeApi = {
  postMessage: (message: unknown) => void;
  getState: <T = unknown>() => T | undefined;
  setState: <T = unknown>(state: T) => void;
};

declare function acquireVsCodeApi(): VSCodeApi;

VS Code provides acquireVsCodeApi() inside the webview, but TypeScript does not know about it by default. This file adds the type information needed by webview-ui/src/api/vscode-api.ts.

The wrapper checks typeof acquireVsCodeApi === "function" because the function only exists inside VS Code, not when previewing the React app in a normal browser.

Create `webview-ui/src/App.tsx`

Now create webview-ui/src/App.tsx :

import { useEffect, useState } from "react";
import {
  VSCodeButton,
  VSCodeCard,
  VSCodeSecondaryButton,
  VSCodeTextArea,
  VSCodeTextField,
} from "./components/vscode-ui";
import { getVsCodeState, postMessage, setVsCodeState } from "./api/vscode-api";

type AppState = {
  projectName: string;
  format: string;
  notes: string;
};

type ExtensionMessage =
  | {
      type: "settingsSaved";
      payload: {
        savedAt: string;
      };
    }
  | {
      type: "fromExtension";
      payload: {
        message: string;
      };
    };

const defaultState: AppState = {
  projectName: "Jupytext Pair Helper",
  format: "ipynb,py:percent",
  notes: "",
};

function App() {
  const savedState = getVsCodeState<AppState>();

  const [projectName, setProjectName] = useState(
    savedState?.projectName ?? defaultState.projectName
  );
  const [format, setFormat] = useState(savedState?.format ?? defaultState.format);
  const [notes, setNotes] = useState(savedState?.notes ?? defaultState.notes);
  const [status, setStatus] = useState("Ready");

  useEffect(() => {
    setVsCodeState({ projectName, format, notes });
  }, [projectName, format, notes]);

  useEffect(() => {
    function handleMessage(event: MessageEvent<ExtensionMessage>) {
      const message = event.data;

      switch (message.type) {
        case "settingsSaved":
          setStatus(`Settings saved at ${message.payload.savedAt}`);
          break;
        case "fromExtension":
          setStatus(message.payload.message);
          break;
      }
    }

    window.addEventListener("message", handleMessage);

    return () => {
      window.removeEventListener("message", handleMessage);
    };
  }, []);

  function saveSettings() {
    postMessage({
      type: "saveSettings",
      payload: {
        projectName,
        format,
        notes,
      },
    });
  }

  function showInfoMessage() {
    postMessage({
      type: "showInfo",
      payload: {
        message: `Current project: ${projectName}`,
      },
    });
  }

  function resetSettings() {
    setProjectName(defaultState.projectName);
    setFormat(defaultState.format);
    setNotes(defaultState.notes);
    setStatus("Reset locally. Click Save settings to send the update to VS Code.");
  }

  return (
    <main className="min-h-screen p-5">
      <section className="mx-auto grid max-w-4xl gap-5">
        <VSCodeCard>
          <p className="text-xs uppercase tracking-wide text-[var(--vscode-descriptionForeground)]">
            VS Code Webview Tutorial
          </p>
          <h1 className="mt-2 text-2xl font-semibold text-[var(--vscode-foreground)]">
            React + Vite + Tailwind + VS Code Message Passing
          </h1>
          <p className="mt-2 max-w-2xl text-sm leading-6 text-[var(--vscode-descriptionForeground)]">
            This webview uses React for state, Tailwind for layout, and VS Code message
            passing to communicate with the extension.
          </p>
        </VSCodeCard>

        <div className="grid gap-5 md:grid-cols-2">
          <VSCodeCard>
            <h2 className="text-lg font-medium">Settings</h2>
            <div className="mt-4 grid gap-4">
              <label className="grid gap-1 text-sm">
                <span className="text-[var(--vscode-descriptionForeground)]">Project name</span>
                <VSCodeTextField
                  value={projectName}
                  onChange={(event) => setProjectName(event.target.value)}
                />
              </label>

              <label className="grid gap-1 text-sm">
                <span className="text-[var(--vscode-descriptionForeground)]">Pairing format</span>
                <select
                  value={format}
                  onChange={(event) => setFormat(event.target.value)}
                  className="w-full rounded border border-[var(--vscode-dropdown-border)] bg-[var(--vscode-dropdown-background)] px-3 py-2 text-sm text-[var(--vscode-dropdown-foreground)] focus:outline focus:outline-1 focus:outline-[var(--vscode-focusBorder)]"
                >
                  <option value="ipynb,py:percent">Python percent pair</option>
                  <option value="ipynb,md:myst">Markdown MyST pair</option>
                  <option value="ipynb,md,pct.py:percent">
                    Notebook + Markdown + percent script
                  </option>
                </select>
              </label>

              <label className="grid gap-1 text-sm">
                <span className="text-[var(--vscode-descriptionForeground)]">Notes</span>
                <VSCodeTextArea
                  value={notes}
                  onChange={(event) => setNotes(event.target.value)}
                  placeholder="Notes about the selected pairing format..."
                />
              </label>

              <div className="flex flex-wrap gap-2">
                <VSCodeButton onClick={saveSettings}>Save settings</VSCodeButton>
                <VSCodeButton onClick={showInfoMessage}>Show VS Code message</VSCodeButton>
                <VSCodeSecondaryButton onClick={resetSettings}>Reset</VSCodeSecondaryButton>
              </div>
            </div>
          </VSCodeCard>

          <VSCodeCard>
            <h2 className="text-lg font-medium">Preview</h2>
            <div className="mt-4 grid gap-4">
              <div className="rounded-lg border border-[var(--vscode-panel-border)] p-4">
                <p className="text-sm text-[var(--vscode-descriptionForeground)]">Project</p>
                <h3 className="mt-1 text-lg font-medium">{projectName}</h3>
              </div>

              <div className="rounded-lg border border-[var(--vscode-panel-border)] p-4">
                <p className="text-sm text-[var(--vscode-descriptionForeground)]">
                  Selected Jupytext format
                </p>
                <code className="mt-2 block rounded bg-[var(--vscode-textCodeBlock-background)] p-3">
                  {format}
                </code>
              </div>

              <div className="rounded-lg border border-[var(--vscode-panel-border)] p-4">
                <p className="text-sm text-[var(--vscode-descriptionForeground)]">Status</p>
                <p className="mt-1 text-sm">{status}</p>
              </div>
            </div>
          </VSCodeCard>
        </div>
      </section>
    </main>
  );
}

export default App;

How the interaction works

The React webview sends this message when the user clicks Save settings:

postMessage({
  type: "saveSettings",
  payload: {
    projectName,
    format,
    notes,
  },
});

The extension receives that message, runs extension-side logic, and sends a response back to React.

The React webview receives extension messages here:

window.addEventListener("message", handleMessage);

8. Build the React App

From inside webview-ui, run:

npm run build

Vite creates:

webview-ui/dist/
  index.html
  assets/
    index.js
    index.css

The extension will load these built files into the webview.

9. Add the Webview Command to `package.json`

Open the extension root package.json.

Update contributes.commands:

{
  "contributes": {
    "commands": [
      {
        "command": "react-webview-vite.openPanel",
        "title": "Open React Webview"
      }
    ]
  }
}

Make sure the command name matches the command registered in extension.ts.

10. Create the Webview Panel in `extension.ts`

Replace src/extension.ts with:

import * as vscode from "vscode";

type WebviewMessage =
  | {
      type: "saveSettings";
      payload: {
        projectName: string;
        format: string;
        notes: string;
      };
    }
  | {
      type: "showInfo";
      payload: {
        message: string;
      };
    };

export function activate(context: vscode.ExtensionContext) {
  const disposable = vscode.commands.registerCommand(
    "react-webview-vite.openPanel",
    () => {
      const panel = vscode.window.createWebviewPanel(
        "reactWebviewVite",
        "React Webview",
        vscode.ViewColumn.One,
        {
          enableScripts: true,
          localResourceRoots: [
            vscode.Uri.joinPath(context.extensionUri, "webview-ui", "dist"),
          ],
        }
      );

      panel.webview.html = getWebviewHtml(panel.webview, context.extensionUri);

      panel.webview.onDidReceiveMessage(
        async (message: WebviewMessage) => {
          switch (message.type) {
            case "saveSettings": {
              await context.globalState.update(
                "reactWebviewVite.settings",
                message.payload
              );

              vscode.window.showInformationMessage(
                `Saved settings for ${message.payload.projectName}`
              );

              panel.webview.postMessage({
                type: "settingsSaved",
                payload: {
                  savedAt: new Date().toLocaleTimeString(),
                },
              });

              break;
            }

            case "showInfo": {
              vscode.window.showInformationMessage(message.payload.message);

              panel.webview.postMessage({
                type: "fromExtension",
                payload: {
                  message: "VS Code received the message and showed a notification.",
                },
              });

              break;
            }
          }
        },
        undefined,
        context.subscriptions
      );
    }
  );

  context.subscriptions.push(disposable);
}

function getWebviewHtml(webview: vscode.Webview, extensionUri: vscode.Uri) {
  const scriptUri = webview.asWebviewUri(
    vscode.Uri.joinPath(extensionUri, "webview-ui", "dist", "assets", "index.js")
  );

  const styleUri = webview.asWebviewUri(
    vscode.Uri.joinPath(extensionUri, "webview-ui", "dist", "assets", "index.css")
  );

  const nonce = getNonce();

  return /* html */ `
    <!DOCTYPE html>
    <html lang="en">
      <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />

        <meta
          http-equiv="Content-Security-Policy"
          content="default-src 'none'; img-src ${webview.cspSource} https:; style-src ${webview.cspSource} 'unsafe-inline'; script-src 'nonce-${nonce}';"
        />

        <link rel="stylesheet" href="${styleUri}" />
        <title>React Webview</title>
      </head>
      <body>
        <div id="root"></div>
        <script type="module" nonce="${nonce}" src="${scriptUri}"></script>
      </body>
    </html>
  `;
}

function getNonce() {
  let text = "";
  const possible =
    "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";

  for (let i = 0; i < 32; i++) {
    text += possible.charAt(Math.floor(Math.random() * possible.length));
  }

  return text;
}

export function deactivate() {}

Important details:

enableScripts: true allows the React bundle to run.
localResourceRoots allows the webview to read files from webview-ui/dist.
webview.asWebviewUri(...) converts extension file paths into safe webview URLs.
context.extensionUri points to the extension root folder, not the out/ folder.
The compiled extension runs from out/extension.js, but it can still reference webview-ui/dist/assets/index.js relative to the extension root.
The CSP uses a nonce so only the intended script can run.

11. Run Both Development Watchers

From your terminal, make sure you are in the extension root folder:

cd react-webview-vite

For development, run the extension's TypeScript watcher and the Vite webview watcher at the same time.

You need both because they build different parts of the project:

Extension watcher → compiles src/extension.ts into out/extension.js
Webview watcher   → builds React/Tailwind files into webview-ui/dist/

Use concurrently because both watcher commands are long-running processes.

From the extension root, install it:

npm install -D concurrently

Add these scripts to the extension root package.json:

{
  "scripts": {
    "watch": "tsc -watch -p ./",
    "watch:webview": "npm --prefix webview-ui run build -- --watch",
    "dev": "concurrently \"npm run watch\" \"npm run watch:webview\""
  }
}

Now start both watchers from the extension root:

npm run dev

This keeps both outputs updated while you work:

out/extension.js
webview-ui/dist/assets/index.js
webview-ui/dist/assets/index.css

12. Start and Reload the Extension

To start the extension:

Open the extension project in VS Code.
Press F5.
A new Extension Development Host window opens.
Open the Command Palette.
Run:

Open React Webview

The React webview should appear.

Reloading after changes

There are two common reload flows.

If you changed React code

Keep npm run dev running from the extension root.
Close the webview panel.
Run Open React Webview again.

Usually you do not need to restart the full Extension Development Host for React-only changes.

If you changed the extension code

If you changed src/extension.ts or package.json:

Go to the Extension Development Host window.
Press:

Ctrl + R

On macOS, use:

Cmd + R

This reloads the Extension Development Host.

Then run:

Open React Webview

again from the Command Palette.

13. Production Build

Before packaging or publishing the extension, build both parts:

npm run compile
npm --prefix webview-ui run build

You should commit or package the built webview assets depending on your publishing workflow.

14. Quick Checks

Before running the extension, confirm these files exist:

out/extension.js
webview-ui/dist/assets/index.js
webview-ui/dist/assets/index.css

Also confirm the command ID matches in both places:

package.json → contributes.commands[].command
src/extension.ts → vscode.commands.registerCommand(...)

If the webview is blank, open VS Code Developer Tools with:

Developer: Toggle Developer Tools

15. Final Folder Structure

react-webview-vite/
  package.json
  tsconfig.json
  src/
    extension.ts
  out/
    extension.js
    extension.js.map
  webview-ui/
    package.json
    vite.config.ts
    index.html
    src/
      App.tsx
      main.tsx
      index.css
    dist/
      assets/
        index.js
        index.css

Summary

You now have a VS Code extension that:

Registers a command in the Command Palette
Opens a custom webview panel
Loads a React app built by Vite
Uses Tailwind CSS for layout and styling
Uses small reusable React components styled with VS Code theme variables
Supports a practical reload workflow during development

The key development loop is:

npm run dev

Then:

F5 → Open React Webview → edit React → close/reopen panel → edit extension → Ctrl/Cmd + R

Source Code : https://github.com/moyarich/react-webview-vite

Fix Python Imports in Jupyter Notebooks

Moya Richards — Tue, 28 Apr 2026 14:04:55 +0000

If you've ever opened a Jupyter notebook and seen this error:

ModuleNotFoundError: No module named 'app'

…even though the file clearly exists — you're running into one of the most common (and frustrating) notebook issues: Python import context.

This usually happens because Jupyter:

Runs inside an already-started Python process
Does not treat your code as part of a package
Depends entirely on the current working directory and sys.path

So even well-structured projects break when you try to import them from a notebook.

In normal Python execution, the fix is to use:

python -m app.module
or install your project with pip install -e .

But those solutions don’t apply inside Jupyter notebooks.

When testing or debugging your app in a notebook, most developers fall back to hacking sys.path — which works, but quickly becomes messy and hard to manage.

Instead, we can fix this cleanly with a reusable, scoped utility:

👉 RelativeImportContext

💡 Why this matters: RelativeImportContext gives you package-style imports inside a notebook without polluting global state, restarting the kernel, or restructuring your project.

What It Does

Temporarily adds directories to sys.path
Restores everything safely after execution
Captures logs during import/debugging
Works as both a context manager and decorator

Install:

pip install relative-import-context

Example 1: Fix Local Imports

with RelativeImportContext("./app"):
    from services.user import get_user

No more ModuleNotFoundError when running scripts from outside the project root.

Example 2: Multiple Package Roots

with RelativeImportContext(["./app", "./libs"]):
    import service
    import utils

Example 3: Capture Logs During Import

with RelativeImportContext("./app") as ctx:
    import my_module

print(ctx.get_logs())

Great for debugging import side effects.

Example 4: Target a Specific Logger

import logging

logger = logging.getLogger("my_app")

with RelativeImportContext("./app", logger_name="my_app") as ctx:
    logger.info("Starting...")

print(ctx.get_logs())

Example 5: Use as a Decorator

@RelativeImportContext("./app")
def run():
    import my_module
    print("Loaded")

run()

Example 6: Debug Failing Imports

try:
    with RelativeImportContext("./app") as ctx:
        import broken_module
except Exception as e:
    print("Error:", e)
    print(ctx.get_logs())

Why This Is Better Than sys.path Hacks

Approach	Problem
`sys.path.append()` scattered everywhere	Hard to track, pollutes global state
Environment variables (PYTHONPATH)	Not portable, hard to debug
RelativeImportContext	Scoped, safe, debuggable

Where This Shines

This pattern is especially useful in:

Local development without packaging
Projects with scripts
CLI tools
Testing/Debugging

Key Benefits

✅ Zero global side effects
✅ Safe restoration of state
✅ Debug-friendly logging
✅ Reusable and composable
✅ Works as context manager + decorator

The Better Long-Term Fix: `python -m`

While RelativeImportContext is useful, the real solution is understanding how Python runs modules.

What `-m` Does

When you run:

python -m app.tasks

Python:

Treats app as a package
Adds the project root to sys.path
Executes tasks.py as part of that package

Instead of treating it as a standalone file.

Why This Fixes Imports

Without -m:

python app/tasks.py

Python sets sys.path to the folder containing the file (app/)
So app is no longer a top-level package
This breaks imports like:

from app.db import SessionLocal

With -m:

python -m app.tasks

Python runs from the project root
app stays a valid package
All absolute imports work correctly

Mental Model

Think of it like this:

Command	How Python Thinks
`python file.py`	"Just run this file"
`python -m package.module`	"Run this as part of a package"

Real Project Example

Project structure:

project/
  app/
    __init__.py
    db.py
    tasks.py

Correct way:

cd project
python -m app.tasks

Now this works everywhere:

from app.db import SessionLocal

When to Use Each Approach

Situation	Best Tool
Running real app / workers	`python -m`
Production-ready projects	install with `pip install -e .`
Quick scripts / testing/debugging	`RelativeImportContext`

Does `python -m` Work in Jupyter Notebooks?

Short answer: No — not directly.

Why Not?

Jupyter notebooks do not run code the same way as the terminal.

When you execute a cell, Python:

Runs code inside an already-running interpreter
Does not treat cells as modules or packages
Does not support python -m execution semantics

So this will NOT work inside a notebook:

# ❌ This does NOT behave like terminal execution
python -m app.tasks

What Actually Happens in Jupyter

Jupyter behaves more like running:

python
>>> # interactive session

So imports depend entirely on:

Current working directory (os.getcwd())
Existing sys.path

How to Handle Imports in Jupyter

Option 1: Adjust `sys.path`

import sys
sys.path.append("/path/to/project")

Works, but it's a global hack.

Option 2: Use `RelativeImportContext` (Cleanest for Notebooks)

👉 Important: This is one of the best real-world uses for RelativeImportContext.

Unlike production apps where python -m or proper packaging is preferred, Jupyter runs in an already-active interpreter. That means you can’t rely on module execution semantics — but you still need clean, scoped imports.

RelativeImportContext solves this perfectly by:

Avoiding global sys.path pollution
Keeping imports scoped to a single cell or block
Making debugging easier with captured logs

with RelativeImportContext("./app"):
    from app.db import SessionLocal

This gives you package-style imports inside a notebook, without restructuring your entire project or restarting the kernel.

with RelativeImportContext("./app"):
    from app.db import SessionLocal

This is actually a perfect use case for your utility.

Option 3: Launch Jupyter from Project Root

Best practice:

cd project
jupyter notebook

Then imports like this will work:

from app.db import SessionLocal

Pro Tip

If you frequently use notebooks in a project:

Always open Jupyter from the project root
Or install your project:

pip install -e .

Then imports work everywhere — notebook, scripts, workers.

Summary

Environment	Best Approach
Terminal scripts	`python -m`
Jupyter notebooks	project root OR `RelativeImportContext`
Production	`pip install -e .`

Instead of fighting Python’s import system…

control it — safely and locally.

RelativeImportContext turns a messy problem into a clean, reusable pattern.

Python Implementation

import logging
import sys
from contextlib import ContextDecorator
from io import StringIO
from pathlib import Path
from types import TracebackType
from typing import Iterable, Optional, Self, Type


class RelativeImportContext(ContextDecorator):
    def __init__(
        self,
        package_directories: str | Path | Iterable[str | Path],
        *,
        log_level: int = logging.DEBUG,
        logger_name: Optional[str] = None,
    ) -> None:
        if isinstance(package_directories, (str, Path)):
            package_directories = [package_directories]

        self.package_directories = [
            str(Path(directory).expanduser().resolve())
            for directory in package_directories
        ]

        self.log_level = log_level
        self.logger_name = logger_name

        self._original_sys_path: list[str] = []
        self._log_stream = StringIO()
        self._log_handler = logging.StreamHandler(self._log_stream)
        self._log_handler.setLevel(log_level)
        self._log_handler.setFormatter(
            logging.Formatter("%(levelname)s:%(name)s:%(message)s")
        )

        self._logger: logging.Logger | None = None
        self._old_logger_level: int | None = None
        self._entered = False

    def __enter__(self) -> Self:
        if self._entered:
            raise RuntimeError("Cannot re-enter the same context instance")

        self._entered = True
        self._original_sys_path = list(sys.path)

        for directory in reversed(self.package_directories):
            if directory not in sys.path:
                sys.path.insert(0, directory)

        self._logger = logging.getLogger(self.logger_name)
        self._old_logger_level = self._logger.level

        if self._logger.level > self.log_level or self._logger.level == logging.NOTSET:
            self._logger.setLevel(self.log_level)

        self._logger.addHandler(self._log_handler)
        return self

    def __exit__(
        self,
        exc_type: Type[BaseException] | None,
        exc_value: BaseException | None,
        traceback: TracebackType | None,
    ) -> bool:
        sys.path[:] = self._original_sys_path

        if self._logger is not None:
            self._logger.removeHandler(self._log_handler)

            if self._old_logger_level is not None:
                self._logger.setLevel(self._old_logger_level)

        self._log_handler.flush()
        self._entered = False
        return False

    def get_logs(self) -> str:
        return self._log_stream.getvalue()

    def clear_logs(self) -> None:
        self._log_stream.seek(0)
        self._log_stream.truncate(0)

Split your AWS AppSync schema across multiple files

Moya Richards — Sat, 18 Apr 2026 04:46:24 +0000

If you’re working with AWS AppSync or any modular GraphQL API, you’ve probably want to split your schema across multiple files. This is great for developer sanity—but AppSync prefers a single .graphql file.

Let’s automate that.

This post walks through a simple Node.js script that uses the @graphql-tools ecosystem to:

✅ Load and merge your GraphQL schemas
✅ Resolve conflicts
✅ Write the final result to a single .graphql file
✅ load schema into your AppSync deployment flow

🛠 Setup

Install the necessary dependencies:

npm install @graphql-tools/load-files @graphql-tools/merge graphql

📦 Your Project Structure

Assume your project is organized like this:

project-root/
├── appsync/
│   ├── mutations/
│   │   └── addCustomer.graphql
│   ├── queries/
│   │   └── getCustomer.graphql
│   └── schema_chatbot_quicksight_merged.graphql (output)
├── mergeSchemas.js

🧩 The Merge Script

Here’s the full script to merge your GraphQL schema files:

import { loadFilesSync } from "@graphql-tools/load-files";
import { mergeTypeDefs } from "@graphql-tools/merge";
import { print } from "graphql";
import fs from "fs";
import path from "path";
import { fileURLToPath } from "url";

try {
    const __filename = fileURLToPath(import.meta.url);
    const __dirname = path.dirname(__filename);
    const mergedFileName = "schema_chatbot_quicksight_merged.graphql";
    const outputPath = path.join(__dirname, "./appsync", mergedFileName);

    const typesArray = loadFilesSync(path.join(__dirname, "./appsync/**/*.graphql"), {
        extensions: [".graphql"],
        ignore: [mergedFileName],
    });

    if (!typesArray || typesArray.length === 0) {
        throw new Error("No GraphQL schema files found");
    }

    console.log(
        "Loaded files:",
        typesArray.map((t) => t?.loc?.source?.name || typeof t),
    );

    const mergedTypeDefs = mergeTypeDefs(typesArray, {
        all: true,
        throwOnConflict: true,
    });

    const sdl = print(mergedTypeDefs);

    const outputDir = path.dirname(outputPath);
    if (!fs.existsSync(outputDir)) {
        fs.mkdirSync(outputDir, { recursive: true });
    }

    fs.writeFileSync(outputPath, sdl);
    console.log(`✅ Merged schema written to appsync/${mergedFileName}`);
} catch (error) {
    console.error("❌ Error merging GraphQL schemas:", error.message);
    process.exit(1);
}

🚀 Using It in AWS CDK

Once your merged schema is generated, you can use it directly in your CDK stack with aws-cdk-lib/aws-appsync.

Here’s an example:

import * as cdk from "aws-cdk-lib";
import { Construct } from "constructs";
import * as appsync from "aws-cdk-lib/aws-appsync";
import * as path from "path";

export class AppsyncStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const api = new appsync.GraphqlApi(this, "graphql-api", {
      name: "ChatbotQuickSightApi",
      schema: appsync.SchemaFile.fromAsset(
        path.join(__dirname, "../appsync/schema_chatbot_quicksight_merged.graphql")
      ),
      authorizationConfig: {
        defaultAuthorization: {
          authorizationType: appsync.AuthorizationType.API_KEY,
        },
      },
      xrayEnabled: true,
    });

    new cdk.CfnOutput(this, "GraphQLAPIURL", {
      value: api.graphqlUrl,
    });
  }
}

🧠 Tip

You can run your mergeSchemas.js script as part of your CDK build pipeline. For example:

"scripts": {
  "prepare-schema": "node mergeSchemas.js",
  "build": "npm run prepare-schema && cdk synth"
}

🧼 Why This Matters

Keep your schema modular for readability and reuse
Deliver a single file AppSync expects without error-prone copy/paste
Enable CI/CD integration with schema validation and bundling in one step

Supercharge AWS Diagrams in VSCode with Mermaid and Custom Icons

Moya Richards — Sat, 18 Apr 2026 04:45:00 +0000

Want to turn your architecture docs into visual gold? With the new Mermaid.js architecture diagram syntax and custom icon packs, you can create AWS diagrams—all from within VSCode using Markdown.

This guide walks you through how to:

✅ Use Mermaid’s new architecture syntax
✅ Set up custom AWS and icon libraries
✅ Preview it all in VSCode using the Markdown Preview Enhanced extension

Let’s dive in. 👇

🔧 Icon Packs You'll Use

Here are the icon libraries we’ll pull in:

These icons can be referenced in your Mermaid diagrams by name (e.g. logos:aws-lambda, aws:aurora, fa: ,).

✅ Step 1: Install Markdown Preview Enhanced

First, install the Markdown Preview Enhanced extension in VSCode.

It enables rich previews for .md files—supporting Mermaid, LaTeX, charts, diagrams, and more.

⚙️ Step 2: Inject Icon Packs into Mermaid

We’ll now customize the Markdown preview to load external icon packs into Mermaid.

How to set it up:

In VSCode, press Ctrl + P, then type:

   > Markdown Preview Enhanced: Customize Preview Html Head (WORKSPACE)

Select the command. It will create a file:

   .crossnote/head.html

Paste the following code into that file:

<!-- Load custom icon packs for Mermaid architecture diagrams -->
<script type="text/javascript">
  const configureMermaidIconPacks = () => {
    window["mermaid"].registerIconPacks([
      {
        name: "logos",
        loader: () =>
          fetch("https://unpkg.com/@iconify-json/logos/icons.json").then(res =>
            res.json()
          ),
      },
      {
        name: "lucide",
        loader: () =>
          fetch("https://unpkg.com/@iconify-json/lucide/icons.json").then(res =>
            res.json()
          ),
      },
      {
        name: "fa",
        loader: () =>
          fetch("https://unpkg.com/@iconify-json/fa/icons.json").then(res =>
            res.json()
          ),
      },
      {
        name: "aws",
        loader: () =>
          fetch(
            "https://raw.githubusercontent.com/awslabs/aws-icons-for-plantuml/aa30729ab2e125f13526020fa98ed5eb0ed86cc1/dist/aws-icons-mermaid.json"
          ).then(res => res.json()),
      },
    ]);
  };

  if (document.readyState !== "loading") {
    configureMermaidIconPacks();
  } else {
    document.addEventListener("DOMContentLoaded", () => {
      configureMermaidIconPacks();
    });
  }
</script>

This ensures Mermaid can load and render your custom icons directly in preview.

🖼️ Step 3: Create a Diagram with AWS Icons

Now create a .md file (e.g. README.md) and embed a Mermaid diagram using the new architecture syntax and icons.

Here’s a full example using AWS services:

Click to expand the Mermaid diagram example

---
config:
  theme: base
  themeVariables:
    darkMode: false
    archEdgeColor: "#232F3E"
    archEdgeArrowColor: "#232F3E"
    archGroupBorderColor: "#ff862a"
---
architecture-beta


service user_service(lucide:user)[Users via Web Browser]

group cdk_infra(cloud)[AWS CDK Infrastructure]

service waf(logos:aws-waf)[AWS WAF] in cdk_infra
service cloudfront(logos:aws-cloudfront)[Amazon CloudFront] in cdk_infra
service cognito(logos:aws-cognito)[Amazon Cognito] in cdk_infra
service s3_front(logos:aws-s3)[Amazon S3 Frontend Hosting] in cdk_infra
service apigw(logos:aws-api-gateway)[Amazon API Gateway] in cdk_infra
service appsync(logos:aws-appsync)[AWS AppSync] in cdk_infra
service cdk_deploy(aws:cloudformation)[AWS CDK Deployment] in cdk_infra

group vpc_private_subnet(cloud)[VPC Private Subnet] in cdk_infra

service lambda(logos:aws-lambda)[AWS Lambda] in vpc_private_subnet
service dynamodb(logos:aws-dynamodb)[Amazon DynamoDB] in vpc_private_subnet
service aurora(logos:aws-aurora)[Amazon Aurora PostgreSQL] in vpc_private_subnet
service sagemaker(aws:sagemaker)[Amazon SageMaker] in vpc_private_subnet
service bedrock(aws:bedrock)[Amazon Bedrock] in vpc_private_subnet
service step_functions(logos:aws-step-functions)[AWS Step Functions] in vpc_private_subnet
service s3_ingest(logos:aws-s3)[Amazon S3 Ingestion] in vpc_private_subnet
service lambda_ingest(logos:aws-lambda)[AWS Lambda Ingestion] in vpc_private_subnet


user_service:R --&gt; L:waf
waf:R --&gt; L:cloudfront
cloudfront:R --&gt; L:cognito
cognito:R --&gt; L:s3_front
s3_front:R --&gt; L:apigw
s3_front:B --&gt; L:appsync
apigw:R --&gt; L:lambda
appsync:R --&gt; L:lambda
lambda:R --&gt; L:dynamodb
lambda:B --&gt; T:aurora
lambda:T --&gt; B:bedrock
sagemaker:R --&gt; B:s3_ingest
step_functions:R --&gt; L:s3_ingest
s3_ingest:R --&gt; L:lambda_ingest
lambda_ingest:R --&gt; L:dynamodb
lambda_ingest:R --&gt; L:aurora
cdk_deploy:R --&gt; L:step_functions

view in the Mermaid Live Editor

🎉 That’s It!

You now have a fully working setup to design AWS diagrams using Mermaid in VSCode—with custom icons and rich architecture syntax. It’s perfect for:

Internal docs and wikis
Cloud architecture planning
README files that actually explain things

🛠 Bonus Tips

If icons don’t appear, double-check you’re in the Markdown Preview Enhanced window (not the default preview).

Automate Post-Deployment Tasks with `cdkTrigger` in AWS CDK

Moya Richards — Fri, 18 Jul 2025 15:40:43 +0000

Deploying infrastructure with AWS CDK is powerful — but sometimes, you want something more than just resources in place. Maybe you want to:

Seed a database after deployment
Populate an S3 bucket with default data
Kick off a workflow
Or simply validate that everything deployed successfully

That's where the cdk-triggers module comes in. In this post, we'll walk through how to use cdk.triggers.Trigger to automatically invoke a Lambda function after a successful CDK deployment.

🔧 What is `cdk.triggers.Trigger`?

The Trigger construct is part of the aws-cdk-lib.triggers module. It allows you to run a Lambda automatically after your stack is deployed — great for bootstrapping and post-deploy configuration tasks.

🧪 Example: Run a Lambda After Resources Are Created

Let’s say you’re deploying:

An S3 bucket
A DynamoDB table
A Lambda that seeds a database

You want the Lambda to run after all the resources are successfully created.

Step 1: Import Required Modules

import * as cdk from "aws-cdk-lib";
import * as lambda from "aws-cdk-lib/aws-lambda";
import * as s3 from "aws-cdk-lib/aws-s3";
import * as dynamodb from "aws-cdk-lib/aws-dynamodb";
import * as triggers from "aws-cdk-lib/triggers";
import { Construct } from "constructs";

Step 2: Define the Stack

export class MyStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // S3 bucket
    const bucket = new s3.Bucket(this, "MyBucket");

    // DynamoDB table
    const table = new dynamodb.Table(this, "MyTable", {
      partitionKey: { name: "id", type: dynamodb.AttributeType.STRING },
    });

    // Lambda function to run post-deploy
    const seedFunction = new lambda.Function(this, "SeedFunction", {
      runtime: lambda.Runtime.NODEJS_18_X,
      handler: "index.handler",
      code: lambda.Code.fromAsset("lambda/seed"),
      timeout: cdk.Duration.minutes(5),
      environment: {
        BUCKET_NAME: bucket.bucketName,
        TABLE_NAME: table.tableName,
      },
    });

    bucket.grantReadWrite(seedFunction);
    table.grantReadWriteData(seedFunction);

    // Create the trigger
    const cdkTrigger = new triggers.Trigger(this, "SeedTrigger", {
      handler: seedFunction,
      timeout: cdk.Duration.minutes(10),
      invocationType: triggers.InvocationType.EVENT, // async invocation
    });

    // Define dependencies – only run trigger after these resources are created
    cdkTrigger.executeAfter(bucket);
    cdkTrigger.executeAfter(table);
  }
}

🔁 How It Works

During deployment, CDK will:

Deploy your stack’s resources (bucket, table, Lambda).
Automatically invoke the seedFunction via the trigger.
Ensure it runs only once (unless you opt to re-run it).

🛠 Notes & Best Practices

The Trigger construct deploys a custom resource under the hood.
The invocationType can be:
- EVENT: Asynchronous (default and recommended for non-critical background jobs)
- REQUEST_RESPONSE: Wait for result (useful for critical tasks, but can cause stack rollback on failure)
You can use cdkTrigger.executeAfter(...) to control execution order and guarantee your resources are ready.
To re-run the trigger every deploy, set cdkTrigger.trigger.runOnUpdate = true.

🧹 Optional: Clean Up After Execution

By default, the Lambda and the trigger stay in place. If you want to clean up the Lambda after running:

cdkTrigger.applyRemovalPolicy(cdk.RemovalPolicy.DESTROY);

Or consider separating your post-deployment logic into a one-time stack.

✅ Summary

cdk.triggers.Trigger is a great way to kick off post-deployment automation in a clean, repeatable way.

Use it to:

Seed databases
Initialize state
Validate configs
Or automate any once-per-deploy logic

No need for separate scripts or manual steps — just CDK.

📁 Example Directory Structure

my-app/
├── bin/
│   └── my-app.ts
├── lib/
│   └── my-stack.ts
├── lambda/
│   └── seed/
│       └── index.ts

🧪 Want to Try It?

Make sure you have the triggers module installed:

npm install aws-cdk-lib constructs

That’s it! Happy automating with CDK! ⚙️

Fixing Lambda to Aurora PostgreSQL Connection Timeout Issues in AWS

Moya Richards — Wed, 09 Jul 2025 17:15:36 +0000

Fixing Lambda to Aurora PostgreSQL Connection Timeout Issues in AWS

"errorMessage": "connection to server at \"my-aurora-database.cluster-xxxxx.region.rds.amazonaws.com\" (10.0.0.1), port 5432 failed: timeout expired"

If you've encountered the dreaded "connection timeout" error when trying to connect your AWS Lambda function to Aurora PostgreSQL, you're not alone.
This post will guide you through the common causes and solutions to this frustrating issue.

The Error

{
  "cause": {
    "errorMessage": "connection to server failed: timeout expired",
    "errorType": "OperationalError"
  }
}

Common Causes

VPC Configuration Issues: Lambda can't reach Aurora
Security Group Misconfigurations: Missing or incorrect inbound/outbound rules
Missing VPC Endpoints: Required for proper AWS service communication
Network ACL Issues: Blocking necessary traffic

Step-by-Step Solution

1. VPC Setup

First, ensure your VPC is properly configured with CDK:

const vpc = new ec2.Vpc(this, 'MyVPC', {
  maxAzs: 2,
  natGateways: 1,
  subnetConfiguration: [
    {
      cidrMask: 24,
      name: 'Private',
      subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS,
    },
    {
      cidrMask: 24,
      name: 'Public',
      subnetType: ec2.SubnetType.PUBLIC,
    }
  ]
});

2. Add Required VPC Endpoints

// Add necessary VPC endpoints
vpc.addInterfaceEndpoint('SecretsManagerEndpoint', {
  service: ec2.InterfaceVpcEndpointAwsService.SECRETS_MANAGER
});

vpc.addInterfaceEndpoint('RDSEndpoint', {
  service: ec2.InterfaceVpcEndpointAwsService.RDS
});

vpc.addGatewayEndpoint('S3Endpoint', {
  service: ec2.GatewayVpcEndpointAwsService.S3
});

3. Configure Security Groups

// Lambda security group
const lambdaSG = new ec2.SecurityGroup(this, 'LambdaSG', {
  vpc,
  description: 'Security group for Lambda functions'
});

// Aurora security group
const auroraSG = new ec2.SecurityGroup(this, 'AuroraSG', {
  vpc,
  description: 'Security group for Aurora'
});

// Allow Lambda to connect to Aurora
auroraSG.addIngressRule(
  lambdaSG,
  ec2.Port.tcp(5432),
  'Allow PostgreSQL access from Lambda'
);

4. Lambda Function Configuration

const lambda = new lambda.Function(this, 'MyFunction', {
  runtime: lambda.Runtime.PYTHON_3_9,
  handler: 'index.handler',
  code: lambda.Code.fromAsset('lambda'),
  vpc: vpc,
  vpcSubnets: {
    subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS
  },
  securityGroups: [lambdaSG],
  timeout: Duration.seconds(30)  // Increase from default 3 seconds
});

5. Database Connection Code

Implement proper connection handling in your Lambda:

import psycopg2
from psycopg2 import OperationalError

def get_db_connection():
    try:
        conn = psycopg2.connect(
            host="your-aurora-endpoint",
            database="your-database",
            user="your-username",
            password="your-password",
            connect_timeout=5,
            keepalives=1,
            keepalives_idle=30,
            keepalives_interval=10,
            keepalives_count=5
        )
        return conn
    except OperationalError as e:
        print(f"Connection error: {e}")
        raise

Troubleshooting Checklist

[ ] Verify Lambda and Aurora are in the same VPC
[ ] Check security group inbound/outbound rules
[ ] Confirm VPC endpoints are properly configured
[ ] Validate subnet configurations
[ ] Review Network ACL settings
[ ] Check Aurora instance status and capacity
[ ] Verify database credentials

Conclusion

Connection timeout issues between Lambda and Aurora typically stem from networking misconfigurations. By following this systematic approach to VPC setup, security groups, and connection handling, you can establish reliable connectivity between your Lambda functions and Aurora PostgreSQL database.
With these implementations, your Lambda functions should successfully connect to Aurora PostgreSQL without timeout issues.

Additional Resources

Resolving AWS Secrets Manager Access in AWS Lambda: A Tale of Two Regions

Moya Richards — Tue, 10 Jun 2025 21:12:15 +0000

Have you ever found yourself scratching your head when your AWS Lambda function works perfectly in one region but fails in another?

Recently, I encountered this exact scenario when moving a function from us-east-1 to eu-west-1.

The culprit? VPC endpoints and Secrets Manager access.

Let's dive into the problem and its solution.

The Problem

Our Lambda function, happily running in us-east-1, suddenly threw this error when deployed to eu-west-1:

An error occurred (AccessDeniedException) when calling the GetSecretValue operation: User: arn:aws:sts::ACCOUNT_ID:assumed-role/ROLE_NAME is not authorized to perform: secretsmanager:GetSecretValue on resource: SECRET_ARN because no identity-based policy allows the secretsmanager:GetSecretValue action

The puzzling part? The IAM permissions were identical in both regions.

The Root Cause

After some investigation, i uncovered the core issue: VPC endpoints. In us-east-1, AWS often provides default VPC endpoints for common services, especially in older accounts or those part of organizations with pre-configured settings. However, these default endpoints don't exist in eu-west-1.

Our Lambda function, configured to run in a VPC for enhanced security, couldn't reach Secrets Manager in eu-west-1 without an explicit VPC endpoint.

The Solution

The fix involves creating a VPC endpoint for Secrets Manager in my eu-west-1 VPC. Here's how i did it using AWS CDK:

First, i modified my VPC construct to include an option for creating a Secrets Manager endpoint:

export interface VpcConstructProps extends cdk.StackProps {
    // ... other properties ...
    readonly hasSecretsManagerEndpoint?: boolean;
}

const defaultProps: Partial<VpcConstructProps> = {
    // ... other defaults ...
    hasSecretsManagerEndpoint: false,
};

Then, in the VPC construct's constructor, i added logic to create the endpoint:

constructor(parent: Construct, name: string, props: VpcConstructProps) {
    // ... existing constructor code ...

    if (props.hasSecretsManagerEndpoint) {
        const secretsManagerEndpoint = vpc.addInterfaceEndpoint("SecretsManagerEndpoint", {
            service: cdk.aws_ec2.InterfaceVpcEndpointAwsService.SECRETS_MANAGER,
        });

        // Suppress cdk-nag warnings
        NagSuppressions.addResourceSuppressions(
            secretsManagerEndpoint,
            [
                {
                    id: 'AwsSolutions-EC23',
                    reason: 'Security Group created by VPC Endpoint allows internal VPC traffic only'
                }
            ],
            true
        );
    }

    // ... rest of constructor code ...
}

Finally, when creating my VPC, i enabled the Secrets Manager endpoint:

const vpc = new VpcConstruct(this, 'MyVPC', {
    // ... other props ...
    hasSecretsManagerEndpoint: true,
});

create a vcp endpoint via AWS CLI

#create vcp endpoint via AWS CLI

# Example VPC details

VPC_ID="vpc-12345abcdef"
SUBNET_IDS="subnet-11111aaaaa subnet-22222bbbbb"
SECURITY_GROUP_ID="sg-33333ccccc"
REGION="eu-west-1"

# Create the VPC endpoint
aws ec2 create-vpc-endpoint \
    --vpc-id $VPC_ID \
    --vpc-endpoint-type Interface \
    --service-name com.amazonaws.$REGION.secretsmanager \
    --subnet-ids $SUBNET_IDS \
    --security-group-ids $SECURITY_GROUP_ID \
    --region $REGION


# To verify the endpoint was created:
aws ec2 describe-vpc-endpoints \
    --filters Name=vpc-id,Values=$VPC_ID \
    --region $REGION

The Outcome

After deploying these changes, my Lambda function in eu-west-1 could successfully access Secrets Manager, just like in us-east-1. The error disappeared, and my application worked consistently across regions.

Lessons Learned

Regional Differences Matter: Always be aware that AWS services and default configurations can vary between regions.
VPC Endpoints are Crucial: When running Lambda in a VPC, consider which AWS services you need to access and ensure appropriate VPC endpoints are in place.
Explicit is Better than Implicit: While some regions might have default endpoints, it's better to explicitly define your infrastructure needs in your IaC code.
Test in Multiple Regions: Always test your applications in all regions where you plan to deploy.

By understanding and addressing these nuances, we can build more robust, portable, and predictable cloud applications. Happy coding!

Fixing “exit code: 255” in AWS CodeBuild

Moya Richards — Mon, 09 Jun 2025 21:51:32 +0000

🚀 CDK Docker Lambda Builds: Multi-Architecture to the Rescue

If you've ever run into this Docker build error while deploying an AWS Lambda with CDK via codebuild:

ERROR: failed to solve: process "/bin/sh -c pip3 install --target \"${LAMBDA_TASK_ROOT}\" -r requirements.txt --no-cache-dir" did not complete successfully: exit code: 255
Failed to build asset EtlAuroraPostgresConstruct/ETLTaskProcessorlambdaFn/AssetImage

...and scratched your head over what was wrong, you're not alone.

After digging in, I found the culprit:

❌ AWS CodeBuild only supports x86_64 (amd64) architecture, but I was building a Lambda targeting arm64.

In this post, I’ll walk through how I fixed it using:

Docker’s ${BUILDPLATFORM} variable
CDK environment config switching
Multi-platform Dockerfile magic

💥 The Problem

If you're building Lambda functions using Docker bundling in CDK and targeting arm64, but your build infrastructure (e.g., CodeBuild) only supports x86_64, you’ll hit architecture mismatches.

Symptoms:

CDK build fails with cryptic Docker errors.
Exit code 255 from pip install.
It works locally on M1/M2 Macs or with arm64 runtimes — but fails in CI/CD.

🛠️ The Solution

✅ Step 1: Use `BUILDPLATFORM` in Your Dockerfile

To avoid architecture mismatch, set the platform explicitly in your Dockerfile:

# syntax=docker/dockerfile:1

FROM --platform=${BUILDPLATFORM} public.ecr.aws/lambda/python:3.12

RUN echo "Build platform: ${BUILDPLATFORM}" && echo "Target architecture: ${TARGETARCH}"

WORKDIR ${LAMBDA_TASK_ROOT}
COPY requirements.txt .

RUN pip3 install -r requirements.txt --no-cache-dir

COPY . .

CMD ["index.lambda_handler"]

💡 ${BUILDPLATFORM} is automatically injected by Docker when using BuildKit and --platform.

✅ Step 2: Add a CDK Architecture Config Switcher

Create a utility to determine platform & architecture based on an environment variable (CDK_LAMBDA_ARCHITECTURE):

// get-architecture-config.ts

import * as cdk from "aws-cdk-lib";
import * as dotenv from "dotenv";

dotenv.config();

export const getArchitectureConfig = () => {
  const arch = process.env.CDK_LAMBDA_ARCHITECTURE || "arm64";

  switch (arch.toLowerCase()) {
    case "arm64":
      return {
        architecture: cdk.aws_lambda.Architecture.ARM_64,
        platform: cdk.aws_ecr_assets.Platform.LINUX_ARM64,
      };
    case "x86_64":
    case "amd64":
      return {
        architecture: cdk.aws_lambda.Architecture.X86_64,
        platform: cdk.aws_ecr_assets.Platform.LINUX_AMD64,
      };
    default:
      throw new Error(`Unsupported architecture: ${arch}`);
  }
};

This allows you to dynamically select the right platform during bundling.

✅ Step 3: Use It in Your CDK Lambda Definition

In your CDK Stack, integrate the platform and architecture selection into the Lambda function:

const { architecture, platform } = getArchitectureConfig();

code: lambda.Code.fromAsset(lambdaFnPath, {
  bundling: {
    image: targetRuntime.bundlingImage,
    command: [
      "bash",
      "-c",
      "pip install --no-cache-dir -r requirements.txt --only-binary=:all: --target /asset-output/python",
    ],
    user: "root",
    platform: platform.platform,
  },
}),
architecture,

✅ Step 4: Deploy with the Right Architecture

To switch architectures on demand, pass an env variable when deploying:

DOCKER_BUILDKIT=1 BUILDX_NO_DEFAULT_ATTESTATIONS=1 CDK_LAMBDA_ARCHITECTURE="amd64" cdk deploy

✅ This forces CDK to build for x86_64, which works inside AWS CodeBuild or other amd64-only systems.

✅ Final Tips

Default to arm64 if you’re developing on an Apple Silicon machine and only override in CI/CD.
Add a .env file or use CI/CD variables to switch easily.
If you want reproducible builds, pin the base image version and dependencies tightly.

.env

export CDK_LAMBDA_ARCHITECTURE="amd64"
export DOCKER_BUILDKIT=1
export BUILDX_NO_DEFAULT_ATTESTATIONS=1

🧪 Conclusion

By using BUILDPLATFORM, environment-based architecture switching, and a bit of CDK magic, you can seamlessly build Docker-based Lambda functions for both arm64 and x86_64, even if your CI/CD platform only supports one.

This approach lets you:

Build natively for your development machine
Deploy reliably from CI/CD
Avoid architecture mismatch errors like exit code 255

Resolving Amazon Elastic Container Registry (ECR) Push Errors

Moya Richards — Sun, 12 Jan 2025 23:49:46 +0000

Step by step guide to resolving Amazon Elastic Container Registry (ECR) issues with Docker Images for CLI and DockerImageFunction

Source Code : Example CDK construct with lambda function:

https://github.com/moyarich/how-to-resolve-amazon-ecr-push-issues

Common ECR Push Errors

Here are some typical errors you might encounter when pushing images to ECR:

Issue Discussion is here: https://github.com/aws/aws-cdk/issues/31548

These are the steps I took to fix the issue below

400 Bad Request Errors - Manifest Issues:

  fail: docker push xyz.dkr.ecr.*.amazonaws.com/cdk-hnb659fds-container-assets-… exited with error code 1: failed commit on ref "manifest-sha256:" … : unexpected status from PUT request to https://xyz.dkr.ecr.*.amazonaws.com/v2/cdk-hnb659fds-container-assets.../manifests/: 400 Bad Request. Failed to publish asset

Lambda Stabilization Failures - InvalidImage:

  Resource handler returned message: "Lambda function ... reached terminal FAILED state due to InvalidImage(ImageLayerFailure: UnsupportedImageLayerDetected - Layer Digest sha256:...) and failed to stabilize" (RequestToken: ..., HandlerErrorCode: NotStabilized)

Fixing ECR Push Errors

1. Enable Docker BuildKit

Set the DOCKER_BUILDKIT environment variable to enable BuildKit

export DOCKER_BUILDKIT=1
export BUILDKIT_PROGRESS=plain

Add these variables to your shell configuration file (e.g., ~/.bashrc, ~/.zshrc, or ~/.profile) to persist the setting.

Alternatively, use `docker buildx` instead of `docker build` for extended BuildKit capabilities

To setup Docker build as a pass-through to Docker Buildx:
First make sure that you have Docker Buildx installed docker buildx version. It's included by default in new versions of Docker Desktop and in Docker Engine.

alias 'docker build'='docker buildx build'

Note: to delete alias unalias 'docker build'

Add this alias to your shell configuration file (e.g., ~/.bashrc, ~/.zshrc, or ~/.profile) to persist the setting.

2. Clean Up ECR Repositories

Prune Local Docker Images: Remove unused local Docker images with:

  docker system prune --all

Delete Empty Images: Locate and remove images with 0-byte layers from the ECR registry using the AWS Management Console or AWS CLI.

Delete empty images via AWS CLI Script

is_command_present() {
    type "$1" >/dev/null 2>&1
}

install_jq() {
    printf "\n${YELLOW}PACKAGE CHECK:${NC}Ensuring that you are up to date on the following package: ${RED}jq${NC}\n"

    printf "\n${GREEN}Checking for jq installation.${NC}\n"

    # Check for jq installation
    if is_command_present "jq"; then
        echo "jq is already installed."
    else
        brew install jq
    fi
}

install_jq

#==============================
repositories=$(aws ecr describe-repositories --region $AWS_DEFAULT_REGION --query 'repositories[*].repositoryName' --output text)

for repo in $repositories; do
    echo "\nProcessing repository: $repo"

    # Get the list of image digests in the repository
    image_ids=$(aws ecr list-images --repository-name $repo --region $AWS_DEFAULT_REGION --query 'imageIds[*]' --output json)

    echo $image_ids | jq -c '.[]' | while read -r image; do
        digest=$(echo $image | jq -r '.imageDigest')

        # Get the image details
        image_details=$(aws ecr describe-images --repository-name $repo --image-ids imageDigest=$digest --region $AWS_DEFAULT_REGION)
        #echo "image_details for $tags:\n $image_details"

        # Get all tags for this image
        tags=$(echo $image_details | jq -r '.imageDetails[0].imageTags[]' 2>/dev/null | tr '\n' ',' | sed 's/,$//')

        image_size=$(echo $image_details | jq '.imageDetails[0].imageSizeInBytes')

        echo "\nImage digest: $digest\nRepository name: $repo \nImage tags: $tags"
        # Check if the image size is 0 bytes
        if [ "$image_size" = "0" ]; then
            echo "Image is empty, deleting image with digest $digest"
            aws ecr batch-delete-image --repository-name $repo --image-ids imageDigest=$digest --region $AWS_DEFAULT_REGION

            # Run the AWS ECR delete command
            output=$(aws ecr batch-delete-image --repository-name $repo --image-ids imageDigest=$digest --region $AWS_DEFAULT_REGION)

            # Check for failures or success
            echo "$output" | jq '
            if .failures | length > 0 then
                "Deletion Failure: \(.failures[0].failureReason)"
            else
                "Success: Image deleted"
            end'
        else
            echo "Image Size: $image_size bytes\nImage not empty [image not deleted]"
        fi
    done
done

3. Create a New ECR Repository Tag for Your ECR Container Docker Image

For Lambda DockerImageFunction, AWS CDK automatically manages image tagging and pushing to Amazon ECR. The image is tagged with a hash based on its content, ensuring that changes result in a new tag.

Options to Force a New Tag in the ECR Registry

Use one of these approaches to force a new tag, repeat this step if you continue to encounter issues with stale or problematic images:

Update the Docker Build Context - IE. Modifying the Lambda Handler Source Code

Modifying files in the Docker build context (many any change to the source code) will trigger a new content-based hash and a new image tag.
Update the Dockerfile

Modifying the Dockerfile (e.g., adding or changing COPY or ENV instructions) will generate a new content hash and tag.
Change the Logical ID of the DockerImageFunction in Your CDK Stack

Renaming the logical ID in the CDK stack forces the creation of a new resource, triggering a new image tag even without content changes.

Example: Changing the Logical ID of a Lambda `DockerImageFunction`

// Old function ID
const prepareDataFn = new cdk.aws_lambda.DockerImageFunction(
  this,
  "PrepareDataLambdaV1Fn",
  {
    code: cdk.aws_lambda.DockerImageCode.fromImageAsset(
      path.join(__dirname, "path-to-docker-build-context")
    ),
  }
);

// New function ID
const prepareDataFn = new cdk.aws_lambda.DockerImageFunction(
  this,
  "PrepareDataLambdaV2Fn",
  {
    code: cdk.aws_lambda.DockerImageCode.fromImageAsset(
      path.join(__dirname, "path-to-docker-build-context")
    ),
  }
);

Example - Command-Line Docker tagging

Provide a new name for the docker tag.
Note: for the cli you tag the image after you build it

docker tag my_image_name:<this_is_my_image_name_tag_here> 241533140213.dkr.ecr.us-east-1.amazonaws.com/cdk-hnb659fds-container-assets-241533140213-us-east-1:<this_is_my_image_name_tag_here>

4. Disable Metadata Attestations

Docker Metadata Attestations Documentation
Avoid potential registry configuration issues by disabling provenance and Software Bill of Materials (SBOM) generation:

Option 1: Use the `BUILDX_NO_DEFAULT_ATTESTATIONS` Environment Variable

export BUILDX_NO_DEFAULT_ATTESTATIONS=1

Option 2: Pass build arguments during the Docker build process to avoid metadata issues during image push

Set sbom to false.
Set the provenance build argument to false.

Example Command-Line Build

DOCKER_BUILDKIT=1 docker build -t my_image_name --provenance=false --sbom=false .

Modify Lambda Function Build Settings in CDK to remove metadata

If using AWS CDK for Lambda deployments, include the provenance and sbom arguments in the buildArgs for your DockerImageFunction.

import * as path from "path";
import * as cdk from "aws-cdk-lib";

const prepareDataFn = new cdk.aws_lambda.DockerImageFunction(
  this,
  "PrepareDataLambdaV1Fn",
  {
    code: cdk.aws_lambda.DockerImageCode.fromImageAsset(
      path.join("../../", "etl/prepare_data"),
      {
        platform: cdk.aws_ecr_assets.Platform.LINUX_ARM64,
        file: "Dockerfile",
        buildArgs: {
          provenance: "false",
          sbom: "false",
        },
      }
    ),
    architecture: cdk.aws_lambda.Architecture.ARM_64,
    description: `Prepare/Clean data - [${cdk.Stack.of(this).stackName}]`,
    timeout: cdk.Duration.minutes(15),
    memorySize: 1024,
  }
);

Automating the Deployment

Automate your deployment process using a package.json configuration to:

Automatically log into ECR
Automatically set DOCKER_BUILDKIT=1

`package.json configuration`

Note: Example package.json [Works on mac/linux, uses sh]:

{
  "scripts": {
    "predeploy": "aws ecr get-login-password | docker login --username AWS --password-stdin $(aws sts get-caller-identity --query 'Account' --output text).dkr.ecr.${AWS_DEFAULT_REGION}.amazonaws.com",
    "deploy": "DOCKER_BUILDKIT=1 sh -c 'cd my_cdk_stacks && npm run cdk deploy -- -c stack_name=\"${STACK_NAME:-}\" --all --require-approval never'",
    "destroy": "npm run cdk destroy -- -c stack_name=\"${STACK_NAME:-}\" --all"
  }
}

CDK Deployment Command:

BUILDKIT_PROGRESS=plain CDK_VPC_ID=vpc-09f66ffff5d2773de STACK_NAME=MoyaTestStack npm run deploy

Example Shell Script for Building and Pushing Docker Images to ECR

# Set variables
IMAGE_NAME="moya_test_image"
TAG="moya_test_image_tag"

REGION=$(aws configure get region --profile "${AWS_PROFILE}")
ACCOUNT_ID=$(aws sts get-caller-identity --query 'Account' --output text)

REPOSITORY_NAME="cdk-hnb659fds-container-assets-${ACCOUNT_ID}-${REGION}"

REGISTRY="${ACCOUNT_ID}.dkr.ecr.${REGION}.amazonaws.com"
FULL_IMAGE_NAME="${REGISTRY}/${REPOSITORY_NAME}:${TAG}"

echo "${FULL_IMAGE_NAME}"

# Build, tag, and push the Docker image

echo "Building Docker image ${IMAGE_NAME}..."

#ECR Issue Discussion - https://github.com/aws/aws-cdk/issues/31549
docker build -t "${IMAGE_NAME}" --provenance=false .

echo "Tagging image as ${FULL_IMAGE_NAME}..."
docker tag "${IMAGE_NAME}" "${FULL_IMAGE_NAME}"

# Login to ECR
echo "Logging into Amazon ECR..."
aws ecr get-login-password | docker login --username AWS --password-stdin $(aws sts get-caller-identity --query 'Account' --output text).dkr.ecr.${REGION}.amazonaws.com

echo "Checking if repository ${REPOSITORY_NAME} exists in ECR..."

# Use aws CLI to check if the repository exists
if aws ecr describe-repositories \
    --repository-names "${REPOSITORY_NAME}" \
    --region "${REGION}" \
    --profile "${AWS_PROFILE}" > /dev/null 2>&1; then
    echo "Repository ${REPOSITORY_NAME} already exists."
else
    echo "Repository ${REPOSITORY_NAME} does not exist in ECR."
fi

echo "Pushing image to ECR..."
docker push "${FULL_IMAGE_NAME}"

Example Code

package.json

{
  "name": "project-root",
  "version": "0.0.1",
  "scripts": {
    "deploy": "DOCKER_BUILDKIT=1 sh -c 'cd my_cdk_stacks && npm run cdk deploy -- -c stack_name=\"${STACK_NAME:-}\" --all --require-approval never'",
    "predeploy": "aws ecr get-login-password | docker login --username AWS --password-stdin $(aws sts get-caller-identity --query 'Account' --output text).dkr.ecr.${AWS_DEFAULT_REGION}.amazonaws.com",
    "destroy": "cd my_cdk_stacks && npm run cdk destroy -- -c stack_name=\"${STACK_NAME:-}\" --all",
    "predeploy.moya.test": "aws ecr get-login-password | docker login --username AWS --password-stdin $(aws sts get-caller-identity --query 'Account' --output text).dkr.ecr.${AWS_DEFAULT_REGION}.amazonaws.com",
    "deploy.moya.test": "DOCKER_BUILDKIT=1 sh -c 'echo \"moyas--$DOCKER_BUILDKIT\" && cd my_cdk_stacks && npm install && cdk deploy --all --require-approval never --app \"npx ts-node src/moya-test-stack.ts\" --context \"stack_name=${STACK_NAME}\"'",
    "destroy.moya.test": "cd my_cdk_stacks && npx cdk destroy --app \"npx ts-node src/moya-test-stack.ts\" -c stack_name=\"${STACK_NAME:-}\" --all"
  }
}

NPM build Command

CDK_VPC_ID=vpc-09f66ffff5d2793de STACK_NAME=MoyaTestStack npm run deploy.moya.test

DockerFile

directory: etl/prepare_data/DockerFile

FROM public.ecr.aws/lambda/python:3.12

# Set the working directory inside the container to Lambda's task root
WORKDIR ${LAMBDA_TASK_ROOT}

# Copy requirements.txt first to leverage Docker's layer caching
COPY requirements.txt .

# Install the specified packages into the Lambda task root
RUN pip3 install --target "${LAMBDA_TASK_ROOT}" -r requirements.txt --no-cache-dir

# Copy the rest of the application code to the Lambda task root
COPY . .

# Set the CMD to the Lambda handler
CMD [ "index.lambda_handler" ]

moya-test-stack.ts

import * as path from "path";
import * as cdk from "aws-cdk-lib";
import { Construct } from "constructs";
import { AwsSolutionsChecks } from "cdk-nag";
import { NagSuppressions } from "cdk-nag/lib/nag-suppressions";

import * as dotenv from "dotenv";
// Load environment variables from a .env file
dotenv.config();

export interface MoyaTestStackProps extends cdk.StackProps {
  vpc?: cdk.aws_ec2.IVpc;
}

export class MoyaTestStack extends cdk.Stack {
  props: MoyaTestStackProps;

  constructor(scope: Construct, id: string, props: MoyaTestStackProps) {
    super(scope, id, props);
    this.props = props;

    const vpc = props?.vpc ?? this.retrieveVpc();

    const backendPythonProjectRoot = path.join(
      __dirname,
      "../../backend/python"
    );

    const prepareDataFn = new cdk.aws_lambda.DockerImageFunction(
      this,
      "PrepareMoyaDataLambdV3FnV1",
      {
        code: cdk.aws_lambda.DockerImageCode.fromImageAsset(
          path.join(backendPythonProjectRoot, "etl/prepare_data"),
          {
            platform: cdk.aws_ecr_assets.Platform.LINUX_ARM64,
            file: "Dockerfile",
            cmd: ["index.lambda_handler"],
            buildArgs: {
              // Issue Discussion: https://github.com/aws/aws-cdk/issues/31548
              // Fix for ECR push error - [Failed to push image: failed commit on ref, unexpected status from PUT request, 400 Bad Request]
              provenance: "false",
              sbom: "false",
            },
          }
        ),

        architecture: cdk.aws_lambda.Architecture.ARM_64,
        description: `Prepare/Clean data - [${cdk.Stack.of(this).stackName}]`,
        timeout: cdk.Duration.minutes(15),
        memorySize: 1024,
        vpc: vpc,
        vpcSubnets: vpc.selectSubnets({
          subnetType: cdk.aws_ec2.SubnetType.PRIVATE_WITH_EGRESS,
        }),
      }
    );

    this.suppressNags();
  }
  /**
   * Retrieves the VPC (Virtual Private Cloud) based on the provided VPC ID.
   * Throws an error if the VPC ID is not provided via the environment variable CDK_VPC_ID.
   *
   * @returns {cdk.aws_ec2.IVpc} The VPC object retrieved from AWS CDK.
   * @throws {Error} Throws an error if CDK_VPC_ID environment variable is not set.
   */
  retrieveVpc() {
    const stack = cdk.Stack.of(this);
    const env = stack.node.tryGetContext("env");
    const vpcId = process.env.CDK_VPC_ID || env?.vpcId;

    if (!vpcId) {
      throw new Error("CDK_VPC_ID environment variable not set");
    }

    const vpc = cdk.aws_ec2.Vpc.fromLookup(this, "Vpc", {
      vpcId: vpcId,
    });

    return vpc;
  }
  private suppressNags(): void {
    const stack = cdk.Stack.of(this);

    // Suppressions for AWS CDK Nag tool
    NagSuppressions.addStackSuppressions(
      stack,
      [
        {
          id: "AwsSolutions-IAM4",
          reason: "AWS managed policies are permitted for demo purposes",
          appliesTo: [
            // Specify the AWS managed policies allowed in this CDK stack.
            // These policies must be specific and non-overly permissive.
            // For example, avoid policies like AmazonS3FullAccess, AmazonSageMakerFullAccess.
            "Policy::arn:<AWS::Partition>:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole",
            "Policy::arn:<AWS::Partition>:iam::aws:policy/service-role/AWSLambdaVPCAccessExecutionRole",
          ],
        },
      ],
      true
    );
  }
}

//-----------------------------
// CDK deploy
//-----------------------------

const app = new cdk.App();
const stackName = app.node.tryGetContext("stack_name") || "MoyaTestStack";
const account =
  app.node.tryGetContext("account") ||
  process.env.CDK_DEPLOY_ACCOUNT ||
  process.env.CDK_DEFAULT_ACCOUNT;
const region =
  app.node.tryGetContext("region") ||
  process.env.CDK_DEPLOY_REGION ||
  process.env.CDK_DEFAULT_REGION;

const moyaTestStack = new MoyaTestStack(app, stackName, {
  env: {
    account: account,
    region: region,
  },
});

cdk.Aspects.of(app).add(
  new AwsSolutionsChecks({ logIgnores: true, verbose: true })
);
app.synth();

The dreaded AWS error : Cannot find version xx.x for postgres

Moya Richards — Thu, 17 Mar 2022 02:52:10 +0000

When creating an AWS stack containing a postgres database table, you might received this error:

Error

Cannot find version 12.3 for postgres (Service: AmazonRDS; Status Code: 400; Error Code: InvalidParameterCombination

Cannot find upgrade path from 14.2 to 12.3. (Service: AmazonRDS; Status Code: 400; Error Code: InvalidParameterCombination

Erroneous code

const engine = DatabaseInstanceEngine.postgres({ version: PostgresEngineVersion.VER_12_3 });

Now this error code : InvalidParameterCombination, and the the message: Cannot find version 12.3 for postgres is not very explicit and doesn't explain what the real issue is.

What the error really means is that version 12.3 for postgres is depreciated and any reference to that version, or any version you are having an issue with, should be removed from your code and replaced with a supported version.

The real issue

AWS requires that you specify the version number for the database when it is being created. However, AWS doesn't keep all versions of that database around indefinitely.

AWS depreciates certain versions, so at some point in the future you will have to change the code to use a supported version of that database.

How to fix the error?

Specify a supported version of the database

Fixed code: version 1

| Simple code|

const engine = DatabaseInstanceEngine.postgres({ version: PostgresEngineVersion.VER_14_2 });

Fixed code: version 2

Use version 2 of the fix, if you don't like to hardcore values in your code that are expected to change.

| Superior code fix|


/**
* Store values in environment variables
* @see https://www.npmjs.com/package/dotenv
*/
const postgresFullVersion = process.env.POSTGRESFULLVERSION ?? "14.2";
const postgresMajorVersion = process.env.POSTGRESMAJORVERSION ?? "14";

/**
* Generate the postgres engine version from the values in the environment variable
*/

const engine = DatabaseInstanceEngine.postgres({
    version: PostgresEngineVersion.of(
      postgresFullVersion,
      postgresMajorVersion,
    ),
  });

How to know which versions of the database is Depreciated and supported

Visit the AWS website

https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/CHAP_PostgreSQL.html


Image: Depreciated 12.x versions of postgres

or Run the AWS CLI code below

After running the command, scroll all the way to the end of the list to see the most recent version of the database supported by AWS

aws rds describe-db-engine-versions --engine postgres --output table


Image: AWS CLI view of current version of postgres

AWS stack creation code (contains error)

import { Stack, StackProps, CfnOutput } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { Vpc, InstanceType, InstanceSize, InstanceClass } from 'aws-cdk-lib/aws-ec2';
import { DatabaseInstance, DatabaseInstanceEngine, PostgresEngineVersion } from 'aws-cdk-lib/aws-rds';


class CdkRdsStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const vpc = new Vpc(this, 'TestVpc', {
      cidr: '10.192.0.0/16',
      maxAzs: 2,
      natGateways: 1,
      enableDnsHostnames: true,
      enableDnsSupport: true
    });

    //Erroneous Line 
    //--------------------------
    const engine = DatabaseInstanceEngine.postgres({ version: PostgresEngineVersion.VER_12_3 });
    //--------------------------

    const dbInstance = new DatabaseInstance(this, 'Test_Postgres_CDK', {
      engine,
      vpc,
      iamAuthentication: true,
      instanceType: InstanceType.of(
        InstanceClass.BURSTABLE3,
        InstanceSize.MICRO
      ),
      databaseName: 'test_postgres'
    });

    new CfnOutput(this, 'dbEndpoint', {
      value: dbInstance.instanceEndpoint.hostname,
    });
  }
}

AWS stack creation code (fixed code)

import { Stack, StackProps, CfnOutput } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { Vpc, InstanceType, InstanceSize, InstanceClass } from 'aws-cdk-lib/aws-ec2';
import { DatabaseInstance, DatabaseInstanceEngine, PostgresEngineVersion } from 'aws-cdk-lib/aws-rds';


class CdkRdsStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const vpc = new Vpc(this, 'TestVpc', {
      cidr: '10.192.0.0/16',
      maxAzs: 2,
      natGateways: 1,
      enableDnsHostnames: true,
      enableDnsSupport: true
    });

    //--- Erroneous Line 
    //const engine = DatabaseInstanceEngine.postgres({ version: PostgresEngineVersion.VER_12_3 });


    //simple fix : version 1
    //const engine = DatabaseInstanceEngine.postgres({ version: PostgresEngineVersion.VER_14_2 });

    //--------------------------
    //--- start : superior code fix , version 2
    const postgresFullVersion = process.env.POSTGRESMAJORVERSION ?? "14.2";
    const postgresMajorVersion = process.env.POSTGRESENGINEVERSION ?? "14";


    const engine = DatabaseInstanceEngine.postgres({
        version: PostgresEngineVersion.of(
          postgresFullVersion,
          postgresMajorVersion,
        ),
      });
    //--- end : superior code fix
    //--------------------------
    const dbInstance = new DatabaseInstance(this, 'Test_Postgres_CDK', {
      engine,
      allowMajorVersionUpgrade: true,
      vpc,
      iamAuthentication: true,
      instanceType: InstanceType.of(
        InstanceClass.BURSTABLE3,
        InstanceSize.MICRO
      ),
      databaseName: 'test_postgres'
    });

    new CfnOutput(this, 'dbEndpoint', {
      value: dbInstance.instanceEndpoint.hostname,
    });
  }
}

Zsh - install git plugin and theme

Moya Richards — Thu, 18 Nov 2021 16:31:43 +0000


Want your terminal to display information about GIT? If the answer is `YES`, let's get to it.

Check if Zsh is installed

Every new Mac uses the Z shell (Zsh) by default, but if it is not available to your system install it using Homebrew.



echo $SHELL

Expected result of the echo $SHELL command : /bin/zsh

Install zsh using Homebrew(if it is not installed):



brew install zsh

# Set zsh as your default shell
chsh -s $(which zsh)

Install Oh My Zsh

Open terminal, run the command



sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

Modify your Oh My Zsh settings

The configuration file for zsh is called .zshrc and lives in your home folder (~/.zshrc).

locate that file and open it



open ~/.zshrc

Modify your Plugins

Add plugins to your shell by adding the name of the plugin to the plugin array in the ~/.zshrc file. Separate the names of plugins with a space



plugins=(git)

Change your Theme

Changing theme is as simple as changing a string in your configuration file. The default theme is robbyrussell. Just change that value to the change theme, and don't forget to .



ZSH_THEME=pygmalion

Apply your changes

To apply the changes you have made to the theme or plugins you need to either

start a new shell instance
reload the configuration for the current shell



#reload configuration
source ~/.zshrc

Install fonts:

You must select a font in the Terminal Preferences, under Profiles, for your zsh theme to display properly

Most Zsh themes use the powerline fonts, so let's install them.

** Install powerline fonts **



# clone
git clone https://github.com/powerline/fonts.git --depth=1
# install
cd fonts
./install.sh
# clean-up a bit
cd ..
rm -rf fonts

Change Font in the Mac OS X Terminal


Image of Terminal without font

Open Terminal, then navigate to Terminal Preferences > Profiles > Font , then click the Change button.
Select Ubuntu Mono derivative Powerline and set the font size to your liking.
Close preferences, and quit Terminal.


Expected Result: Image of Terminal with font

Change Font for Terminal in Visual Studio Code?


Image of Terminal in Visual Studio Code without font

Open settings.json in VSCode

Press command + shift + p in your VSCode window. Then, search for settings.json and open it.

Add this line to the settings.json :



{
  "terminal.integrated.defaultProfile.osx": "zsh",
  "terminal.integrated.fontFamily": "Ubuntu Mono derivative Powerline",
  "terminal.integrated.fontSize": 12
}


Image of Terminal in Visual Studio Code with font

DEV Community: Moya Richards

Build a VS Code Webview with Vue, Vite, Tailwind CSS, and VS Code-Themed Components

1. Prerequisites

2. Create the VS Code Extension

3. Run the Extension for the First Time

4. Add a Vue App with Vite

5. Install Tailwind CSS for Vite

6. Create VS Code-Themed Vue Components

7. Create the Vue Webview UI with VS Code API Messaging

Create the VS Code API wrapper

Add webview API types for the wrapper

Create webview-ui/src/components/Webview.vue

How the interaction works

8. Make App.vue Render Webview.vue

9. Build the Vue App

10. Add the Webview Command to package.json

11. Create the Webview Panel in extension.ts

12. Run Both Development Watchers

13. Start and Reload the Extension

Reloading after changes

If you changed Vue code

If you changed extension code

14. Production Build

15. Quick Checks

16. Final Folder Structure

Summary

Source Code

Build a VS Code Webview with React, Vite, Tailwind CSS, and VS Code-Themed Components

1. Prerequisites

2. Create the VS Code Extension

3. Run the Extension for the First Time

4. Add a React App with Vite

5. Install Tailwind CSS for Vite

6. Create VS Code-Themed React Components

7. Create the React Webview UI with VS Code API Messaging

Create the VS Code API wrapper

Add webview API types for the wrapper

Create webview-ui/src/App.tsx

How the interaction works

8. Build the React App

9. Add the Webview Command to package.json

10. Create the Webview Panel in extension.ts

11. Run Both Development Watchers

12. Start and Reload the Extension

Reloading after changes

If you changed React code

If you changed the extension code

13. Production Build

14. Quick Checks

15. Final Folder Structure

Summary

Source Code : https://github.com/moyarich/react-webview-vite

Fix Python Imports in Jupyter Notebooks

What It Does

Example 1: Fix Local Imports

Example 2: Multiple Package Roots

Example 3: Capture Logs During Import

Example 4: Target a Specific Logger

Example 5: Use as a Decorator

Example 6: Debug Failing Imports

Why This Is Better Than sys.path Hacks

Where This Shines

Key Benefits

The Better Long-Term Fix: python -m

What -m Does

Why This Fixes Imports

Mental Model

Real Project Example

When to Use Each Approach

Does python -m Work in Jupyter Notebooks?

Why Not?

What Actually Happens in Jupyter

How to Handle Imports in Jupyter

Option 1: Adjust sys.path

Option 2: Use RelativeImportContext (Cleanest for Notebooks)

Option 3: Launch Jupyter from Project Root

Pro Tip

Summary

Python Implementation

Split your AWS AppSync schema across multiple files

Create `webview-ui/src/components/Webview.vue`

8. Make `App.vue` Render `Webview.vue`

10. Add the Webview Command to `package.json`

11. Create the Webview Panel in `extension.ts`

Create `webview-ui/src/App.tsx`

9. Add the Webview Command to `package.json`

10. Create the Webview Panel in `extension.ts`

The Better Long-Term Fix: `python -m`

What `-m` Does

Does `python -m` Work in Jupyter Notebooks?

Option 1: Adjust `sys.path`

Option 2: Use `RelativeImportContext` (Cleanest for Notebooks)

🔧 What is `cdk.triggers.Trigger`?

✅ Step 1: Use `BUILDPLATFORM` in Your Dockerfile

Alternatively, use `docker buildx` instead of `docker build` for extended BuildKit capabilities

Example: Changing the Logical ID of a Lambda `DockerImageFunction`