DEV Community: Kamil Dzieniszewski

I shipped a Chrome extension that runs an LLM with no server, no build step, and no dependencies. Here's what the Prompt API is really like.

Kamil Dzieniszewski — Mon, 13 Jul 2026 15:54:35 +0000

We've all typed a reply, hit post, and regretted the tone ten minutes later. I built Comment Vibe, a Chrome extension that shows a small badge next to any comment box (LinkedIn, X, YouTube, generic contenteditable) with the detected tone of what you're typing — and offers a kinder rewrite when you sound harsh.

The interesting part isn't the product. It's the constraint: everything runs on-device via Chrome's built-in Gemini Nano. No server, no API key, no analytics, no network requests. The whole extension is a handful of raw MV3 files — no npm, no bundler. When your pitch is "your comments never leave your machine," the best privacy audit is cat content.js.

This post is everything I wish I'd known about the Prompt API before starting.

The Prompt API is actually stable now

The LanguageModel API went stable for extensions in Chrome 138 and stable on the open web in Chrome 148. No flags, no origin trial tokens. Chrome downloads Gemini Nano (~2–4 GB) automatically on first use, on eligible hardware (desktop, 16 GB+ RAM, >4 GB VRAM, 22 GB free disk).

That hardware floor is the real trade-off: you get zero infra cost and perfect privacy, but a chunk of your users simply can't run it. Your UX must degrade gracefully — mine shows an availability check in the popup and otherwise stays silent.

Lesson 1: You still have to probe two namespaces

Older builds expose the legacy window.ai.languageModel; newer ones the global LanguageModel. Different Chrome builds ship different namespaces depending on where they were in the origin-trial timeline, so I probe both — and feature-detect initialPrompts support with a retry ladder:

async function constructSession() {
  if (typeof LanguageModel !== 'undefined') {
    const avail = await LanguageModel.availability();
    if (avail === 'unavailable') throw new Error('unavailable');
    const initialPrompts = [{ role: 'system', content: SYSTEM_PROMPT }, ...FEW_SHOT];
    try {
      return sessionMetadata(await LanguageModel.create({ initialPrompts, ...LANGUAGE_OPTIONS }), true);
    } catch (error) {
      if (!supportsReducedOptionsRetry(error)) throw error;
      try {
        return sessionMetadata(await LanguageModel.create({ initialPrompts }), true);
      } catch (reducedError) {
        if (!supportsReducedOptionsRetry(reducedError)) throw reducedError;
        // older builds without initialPrompts support
        return sessionMetadata(await LanguageModel.create({ systemPrompt: SYSTEM_PROMPT }), false);
      }
    }
  }
  if (typeof window !== 'undefined' && window.ai?.languageModel) {
    const { available } = await window.ai.languageModel.capabilities();
    if (available === 'no') throw new Error('unavailable');
    return sessionMetadata(await window.ai.languageModel.create({ systemPrompt: SYSTEM_PROMPT }), false);
  }
  throw new Error('Chrome AI not found');
}

Unsupported options throw TypeError or NotSupportedError, so each fallback strips one capability and retries. Ugly, but it's what "works on every Chrome since 127" costs.

Lesson 2: Sessions are stateful — clone, don't reuse

This one bit me. A Prompt API session keeps its conversation history. If you prompt the same session repeatedly, every analysis appends to its context: each call gets slower, and eventually you overflow the session quota.

The fix: keep one warm base session (creating a session is expensive — it can load the model), and clone() a throwaway per analysis. A clone starts fresh from the initial prompts and is cheap:

const acquired = await getSession();          // cached, warm base session
const session = acquired.cloneCapable
  ? await acquired.session.clone()            // fresh context, no model reload
  : acquired.session;
try {
  // ... prompt on the clone
} finally {
  session.destroy?.();
}

Bonus: baking the system prompt and few-shot examples into initialPrompts means they survive the clone — you don't re-send them with every request.

Lesson 3: Prefill the assistant response to force JSON

Gemini Nano is a small model. Ask it politely for JSON and you'll get JSON most of the time, wrapped in markdown fences some of the time, and a friendly paragraph on bad days. Two tricks got me to reliable structured output:

Few-shot examples in the session's initial prompts, plus an assistant prefill — you hand the model the beginning of its own answer and it continues from there:

const messages = [
  { role: 'user',      content: `Classify the tone of this comment:\n"${text}"` },
  { role: 'assistant', content: '{"sentiment":', prefix: true },   // ← prefill
];
const raw = await session.prompt(messages);
const result = normalize(parseResponse('{"sentiment":' + raw));

The prefix: true flag means the model must start its response mid-JSON. As a side effect, sentiment is guaranteed to be the first field — which enables the streaming trick below.

Lesson 4: Stream, and act on the first parseable field

With promptStreaming() the badge colors in as soon as the sentiment value is readable, while the reason and rewrite are still generating:

async function streamPrompt(session, messages, onEarlySentiment, signal) {
  let raw = '';
  let signaled = false;
  for await (const chunk of callPrompt(session, 'promptStreaming', messages, signal)) {
    // older builds stream the cumulative text, newer ones stream deltas
    raw = (chunk.length > raw.length && chunk.startsWith(raw)) ? chunk : raw + chunk;
    if (!signaled && onEarlySentiment) {
      const m = raw.match(/"(positive|neutral|negative|toxic)"/);
      if (m) { signaled = true; onEarlySentiment(m[1]); }
    }
  }
  return raw;
}

Note the chunk handling: older Chrome builds stream the cumulative text, newer ones stream deltas. That one line handles both.

Lesson 5: Never trust the schema — normalize everything

Even with prefill, a small model improvises key names. Ask for reason, receive tone, analysis, description, or explanation. So the parser maps every synonym the model has ever invented back to the expected shape:

const reasonRaw  = source.reason ?? source.tone ?? source.analysis
                ?? source.description ?? source.explanation ?? '';
const rewriteRaw = source.rewrite ?? source.suggestion
                ?? source.alternative ?? source.improved_version ?? null;

And when JSON parsing fails entirely, there's a last-ditch fallback: regex the raw text for sentiment keywords. A wrong-but-plausible badge beats a broken one.

Lesson 6: Debounce like you mean it

On-device inference is free but not fast. I wait 900 ms after the last keystroke before prompting, wire an AbortController through so a new keystroke cancels the in-flight analysis, and tag requests with an id so a slow stale response can't overwrite a newer result.

Lesson 7: The API zoo is uneven — check before you depend

Chrome ships seven built-in AI APIs, at very different maturity levels:

API	Status	Worth using?
Prompt (`LanguageModel`)	✅ Stable	Yes — the workhorse
Translator / Language Detector	✅ Stable	Yes — they compose beautifully
Summarizer	✅ Stable	Yes
Rewriter	🧪 Dev trial	No — ran a full origin trial, then went back to a flag
Writer	🧪 Dev trial	Not yet
Proofreader	🧪 Origin trial	Not yet

The Rewriter story is the cautionary tale: an API can complete an origin trial and still not graduate. Don't build a hard dependency on anything pre-stable — I do rewrites with the Prompt API instead.

The stable trio composes nicely though: Language Detector identifies what language you're typing in, Translator localizes the feedback and the rewrite into it (cached per language pair, falling back to English), so the suggestion is directly pasteable.

Was "no build tooling" worth it?

Honestly: yes, and more than I expected. No supply chain, nothing to audit but the shipped files, Load unpacked straight from the repo, and the Web Store zip is just zip -r with excludes. The cost is no TypeScript and no bundler-era conveniences — for ~1000 lines of content script, that trade is easy.

Try it

Extension: Comment Vibe on the Chrome Web Store (Chrome 138+, desktop)
Playground for all seven built-in AI APIs — live availability check for your browser plus an interactive demo of each: https://dzienko.dev/comment-vibe/
Source (MIT): [your repo link]

If you're building on the Prompt API and hitting weirdness I didn't cover, drop a comment — I've probably seen it.

I hope not! #meetjs

Kamil Dzieniszewski — Mon, 26 Jan 2026 14:16:16 +0000

Is this my last meet.js Summit?

naugtur ・ Jan 26

I hope not! #meetjs

Kamil Dzieniszewski — Mon, 26 Jan 2026 14:16:16 +0000

Is this my last meet.js Summit?

naugtur ・ Jan 26

Planning a conference? Check this list!

Kamil Dzieniszewski — Fri, 03 Oct 2025 13:23:32 +0000

naugtur

Dec 20 '19

Community Conference Organizer Checklist

10 min read

When 'env' Isn't Just Environment Variables: My Journey Through JavaScript's Module Shorthand Rabbit Hole

Kamil Dzieniszewski — Tue, 26 Aug 2025 14:42:03 +0000

Or: How I spent 3 hours debugging a single word in my config

My Docusaurus Confusion Story

Picture this: I'm upgrading the documentation site for Tolgee (a localization platform I work on), following the Docusaurus migration guide, and I see this line:

presets: [['classic', { /* options */ }]]

Me staring at 'classic' like it personally offended me

"What the hell is 'classic'?" I thought. "Is this some built-in JavaScript thing I missed? A global variable? Magic?"

I spent the next hour:

🔍 Searching my node_modules for anything named "classic"
📖 Reading Docusaurus docs trying to find where this comes from
🤔 Questioning my understanding of JavaScript imports
😤 Getting increasingly frustrated

Then I discovered the truth: 'classic' is actually @docusaurus/preset-classic in disguise. Mind = blown.

But here's the kicker - this "magic" isn't unique to Docusaurus. It's EVERYWHERE in the JavaScript ecosystem.

What Are Module Shorthands?

Module shorthands are a convenience feature that lets you use abbreviated names instead of full package names in configuration files. When a tool encounters a shorthand, it automatically resolves it to the full package name using predefined rules.

The Pattern

Most JavaScript tools follow a similar resolution strategy:

Try exact name first: classic
Try official scoped package: @toolname/type-classic
Try community convention: toolname-type-classic

The first match wins.

The Plot Twist: It's Everywhere!

Once I understood what was happening with Docusaurus, I started seeing this pattern EVERYWHERE. Let me blow your mind with some examples:

Babel - The OG Shorthand Master

Remember that innocent "env" in your Babel config? Yeah, that's not what you think it is.

// babel.config.js
{
  "presets": [
    "env",           // → @babel/preset-env (SURPRISE!)
    "react",         // → @babel/preset-react
    "typescript"     // → @babel/preset-typescript
  ],
  "plugins": [
    "transform-runtime",    // → @babel/plugin-transform-runtime
    "proposal-decorators"   // → @babel/plugin-proposal-decorators
  ]
}

Drake pointing: Writing @babel/preset-env
Drake approving: Writing "env"

Babel has the most sophisticated name normalization system with detailed rules:

Unscoped packages: "mod" → "babel-plugin-mod"
Scoped packages: "@babel/mod" → "@babel/plugin-mod"
Custom scopes: "@scope/mod" → "@scope/babel-plugin-mod"

ESLint - The "Obvious" One (Once You Know)

ESLint actually has the clearest naming convention, but it still trips people up:

// .eslintrc.js
{
  "extends": [
    "airbnb",        // → eslint-config-airbnb
    "prettier",      // → eslint-config-prettier
    "react-app"      // → eslint-config-react-app
  ],
  "plugins": [
    "react",         // → eslint-plugin-react
    "import",        // → eslint-plugin-import
    "jsx-a11y"       // → eslint-plugin-jsx-a11y
  ]
}

Me realizing every config I've ever written is full of hidden magic

ESLint's plugin configuration rules are actually predictable:

Configs: "name" → "eslint-config-name"
Plugins: "name" → "eslint-plugin-name"
Scoped: "@scope/name" → "@scope/eslint-plugin-name"

Back to My Docusaurus Nightmare

Now that I know the pattern, let's revisit my original confusion:

// docusaurus.config.js - The scene of the crime
{
  presets: [
    ['classic', {     // → @docusaurus/preset-classic (THE REVEAL!)
      docs: { /* */ },
      blog: { /* */ }
    }]
  ],
  plugins: [
    'sitemap',        // → @docusaurus/plugin-sitemap
    'content-pages'   // → @docusaurus/plugin-content-pages
  ]
}

Brain 1: "classic" is magic
Brain 2: "classic" is a shorthand
Brain 3: All JS tools use shorthands
Brain 4: I've been using shorthands everywhere without knowing

Docusaurus has comprehensive documentation about this, but finding it when you're confused? Good luck!

PostCSS - Simple Resolution

// postcss.config.js
{
  plugins: [
    "autoprefixer",  // → autoprefixer (exact match)
    "cssnano",       // → cssnano (exact match)
    "tailwindcss"    // → tailwindcss (exact match)
  ]
}

Rollup - Scoped Packages

// rollup.config.js
{
  plugins: [
    "resolve",       // → @rollup/plugin-node-resolve
    "commonjs",      // → @rollup/plugin-commonjs
    "typescript"     // → @rollup/plugin-typescript
  ]
}

Vite - Following the Pattern

// vite.config.js
{
  plugins: [
    "react",         // → @vitejs/plugin-react
    "legacy"         // → @vitejs/plugin-legacy
  ]
}

Why Does This Pattern Even Exist?

After my 3-hour debugging session, I had to ask: WHY do JavaScript tools do this to us?

Convention Over Configuration (The Philosophy)

If a shorthand resolves in a config file and no developer understands it, does it make a sound?

The JavaScript ecosystem LOVES "convention over configuration":

Less typing: 'env' vs '@babel/preset-env' (saved 15 characters!)
Cleaner configs: Your babel.config.js doesn't look like XML
Predictable patterns: Once you know the rules, you can guess package names
Flexibility: Both 'env' and '@babel/preset-env' work

The Ecosystem Benefits (When It Works)

Consistency: Learn it once, recognize it everywhere
Discoverability: "I bet there's an eslint-plugin-react"
Maintainability: Shorter configs are easier to scan
Developer happiness: Less boilerplate = more time for actual coding

The Dark Side: Why It's Absolutely Confusing

Hidden Magic Everywhere

// What you see
presets: [['classic']]

// What actually happens (behind the scenes)
presets: [['@docusaurus/preset-classic']]

Tip of iceberg: Your config
Underwater: All the module resolution happening

There's literally NO visual indication that 'classic' becomes something else entirely.

Documentation Roulette

The docs are inconsistent:

Tutorial shows: 'classic'
API docs show: '@docusaurus/preset-classic'
Stack Overflow shows: Both, with no explanation
Your brain: 🤯

Debugging Hell

When things break, you get errors like:

Cannot resolve module 'classic'

Me trying to figure out which of the 3 resolution attempts failed

The error doesn't tell you:

Which resolution step failed
What was actually attempted
Whether the package is missing or the name is wrong

Every Tool Is Special

Each tool has its own special snowflake implementation:

Babel: Most complex rules
ESLint: Clear patterns but different prefixes
Docusaurus: Scoped packages only
PostCSS: Mostly exact matches
Rollup: Different scope handling

Implementation Deep Dive

How Resolution Actually Works

Most tools implement something like this:

function resolveModule(name, moduleType) {
  const attempts = [
    name,                                    // exact
    `@${toolName}/${moduleType}-${name}`,   // official
    `${toolName}-${moduleType}-${name}`     // community
  ];

  for (const attempt of attempts) {
    try {
      return require.resolve(attempt);
    } catch (e) {
      continue;
    }
  }

  throw new Error(`Cannot resolve ${name}`);
}

Scoped Package Handling

For scoped packages like @my-company/awesome:

function resolveScopedModule(name, moduleType) {
  const [scope, packageName] = name.split('/');

  if (!packageName) {
    // @scope only → @scope/docusaurus-plugin
    return `${scope}/${toolName}-${moduleType}`;
  }

  // @scope/name → try both forms
  const attempts = [
    name,                                           // @scope/name
    `${scope}/${toolName}-${moduleType}-${packageName}` // @scope/docusaurus-plugin-name
  ];

  // ... resolution logic
}

How to Survive the Shorthand Apocalypse

For Tool Authors (Please Listen!)

Drake rejecting: Showing only shorthands in examples
Drake approving: Showing both shorthand AND full names

Document both forms: Show 'classic' AND @docusaurus/preset-classic in examples
Better error messages: Instead of "Cannot resolve 'classic'", show "Tried: classic, @docusaurus/preset-classic, docusaurus-preset-classic"
Cross-reference docs: Link to your shorthand explanation from EVERY config example
Consistent patterns: Don't reinvent the wheel - follow Babel/ESLint conventions

For Developers (My Hard-Learned Lessons)

Me after learning about shorthands: Everything is fine

When confused, use full names: @docusaurus/preset-classic never lies
Check your package.json: See what's actually installed vs what you're referencing
Use IDE superpowers: Many editors show resolved names on hover
Debug systematically: Replace shorthands with full names when things break
Learn the patterns: Once you know Babel's rules, you can guess others

Debugging Shorthand Issues

Common Problems

Package not installed: Shorthand resolves but package missing
Wrong resolution: Resolves to unexpected package
Typos: Small mistakes in shorthand names
Version conflicts: Multiple packages match pattern

Debugging Steps

Try the full name: Replace shorthand with full package name
Check installation: Verify package exists in node_modules
Check resolution: Use tool's debug mode if available
Verify naming: Double-check official package names

Debug Tools

# Check what's installed
npm list | grep preset

# Try resolving manually
node -e "console.log(require.resolve('@docusaurus/preset-classic'))"

# Enable debug mode (tool-specific)
DEBUG=docusaurus* npm start

The Future

Trends

More tools adopting: Pattern spreading to newer tools
Better error messages: Tools improving debugging experience
IDE integration: Better autocomplete and resolution hints
Standardization: Some movement toward common patterns

Recommendations

For the ecosystem to improve:

Better documentation: Always show both forms
Improved tooling: Better IDE support for resolution
Error message standards: Show resolution attempts
Community education: More articles like this one!

The Final Revelation

Small brain: Getting confused by 'classic'
Medium brain: Understanding it's a shorthand
Large brain: Recognizing the pattern everywhere
Galaxy brain: Writing an article to help other confused developers

After my 3-hour journey down the shorthand rabbit hole, I've learned that:

It's not magic: Just very well-hidden conventions
It's everywhere: Once you see it, you can't unsee it
It's actually helpful: When you understand the rules
It's poorly documented: The connection between examples and explanations is often missing

What This Means for You

Next time you see 'env', 'classic', 'airbnb', or any other mysterious string in a JavaScript config:

Don't panic: It's probably a shorthand
Check the tool's docs: Look for "module resolution" or "name normalization"
Try the full name: When in doubt, be explicit
Learn the pattern: Each tool follows similar rules

The JavaScript ecosystem loves its conventions, but sometimes forgets to explain them to newcomers. Now you're in on the secret!

Have you been confused by JavaScript module shorthands? Share your war stories in the comments - let's make the ecosystem more welcoming for everyone! 🚀

About the Author: I work on Tolgee, an open-source localization platform that makes i18n simple for developers. If you're building multilingual apps and tired of complex translation workflows, check us out!

References

🚀 React Compiler is now in RC! No more manual memoization — just write React, and the compiler optimizes it for you. Still experimental, but a big leap forward. 🔗 https://react.dev/blog/2025/04/21/react-compiler-rc #react #javascript #webdev

Kamil Dzieniszewski — Sat, 10 May 2025 18:49:51 +0000

React Compiler v1.0 – React

react.dev