DEV Community: Rabinarayan Patra

How to Configure flake8 for Python (2026 Setup Guide)

Rabinarayan Patra — Tue, 07 Jul 2026 18:30:00 +0000

Every Python project I join eventually hits the same wall. Someone adds flake8, drops the config into pyproject.toml like every other modern tool expects, runs it, and nothing happens. No error, no warning, just flake8 quietly ignoring the entire file. Then the confusion starts.

This guide walks through how to configure flake8 properly in 2026: what it actually is, where its config really lives, why pyproject.toml is the one file it refuses to read, and whether you should still reach for it now that Ruff exists. Everything here is checked against flake8 7.3.0, released June 2025.

What is flake8 and what does it actually check?

flake8 is not one linter. It is a wrapper that glues three separate tools together behind a single command, then adds a plugin system on top. When you run flake8, you are really running pyflakes, pycodestyle, and mccabe in one pass.

Each tool owns a code prefix, and knowing them makes every flake8 report readable:

pyflakes finds logical errors: unused imports, undefined names, unused variables. Its codes start with F.
pycodestyle checks PEP 8 style: whitespace, indentation, line length. It was once called pep8. Its codes start with E (errors) and W (warnings).
mccabe measures cyclomatic complexity. It emits exactly one code, C901 , and only when you turn it on.

flake8 adds one code of its own: E999 , which means the file failed to compile at all (a syntax error). So when you see F401, that is pyflakes telling you about an unused import. E501 is pycodestyle complaining about line length. C901 is mccabe saying a function is too complex.

flake8 7.3.0 pins those dependencies tightly: pyflakes 3.4.x, pycodestyle 2.14.x, and mccabe 0.7.x. It runs on Python 3.9 and up. The project lives under PyCQA (the Python Code Quality Authority) and is maintained by Anthony Sottile and Ian Cordasco.

How do you install and run flake8?

Install it with pip and point it at your code. That is the whole starting workflow:

pip install flake8
flake8 .

That runs flake8 across the current directory. You can target a specific path or module too:

flake8 src/
python -m flake8 src/

The python -m flake8 form is worth remembering. It guarantees you run the flake8 installed in the current environment, which matters the moment you have more than one Python around. On a fresh run with no config, flake8 uses its defaults: 79-character lines and a small built-in ignore list. Most teams change both, which is where config comes in.

Where does flake8 look for its configuration?

flake8 reads three config files, all in INI format under a [flake8] section: setup.cfg, tox.ini, and a dedicated .flake8 file. It does not read anything else, and it does not merge them. It picks one.

I default to a standalone .flake8 file because it keeps linter config out of files that mean other things. Here is a realistic starting point, close to what the official docs recommend:

[flake8]
max-line-length = 88
extend-ignore = E203
exclude = .git, __pycache__ ,docs/source/conf.py,old,build,dist
max-complexity = 10
per-file-ignores =
    __init__.py: F401

A few of those options carry sharp edges, so here is what each one actually does:

max-line-length defaults to 79. Setting it to 88 matches Black, which is why most projects use that number.
extend-ignore adds codes to the ignore list without wiping the defaults. ignore (no extend-) replaces the entire default list, which usually is not what you want. Reach for the extend- forms.
extend-select works the same way for turning checks on. It was added in flake8 4.0.0.
exclude takes comma-separated paths and globs that flake8 skips entirely.
per-file-ignores lets you relax rules per file. The __init__.py: F401 line above silences unused-import warnings in package init files, where re-exporting is normal.
max-complexity turns on the mccabe check. It is off until you set it, so C901 never fires until you add a line like max-complexity = 10.

The extend-ignore = E203 in that example is there for a reason. E203 flags whitespace before a colon, which collides with how Black formats slices. Turning it off is the standard fix for running flake8 and Black together.

Why won't flake8 read your pyproject.toml?

flake8 does not read pyproject.toml, and that is a deliberate decision, not a missing feature. This is the single most common flake8 problem I see, and the answer surprises people: the maintainer has kept the request open for years and does not intend to add it as-is.

The relevant thread is PyCQA/flake8 issue #234, and it is still open. Anthony Sottile's position is direct: "I don't think toml is the way especially with pip continuing to have weird behaviour when the file even exists." His technical objection is real. The mere presence of a pyproject.toml file changes how pip builds a package, because it can force an isolated PEP 517 build. He listed two conditions that would need to hold before he would reconsider: pip no longer changing its behavior based on the file existing, and a standard-library TOML parser. Python 3.11 added tomllib, so half of that is now true, but flake8 7.3.0 still will not read the file.

So what do you do if your project standardizes on pyproject.toml and you want flake8 config to live there too? Use a plugin.

pip install Flake8-pyproject

Flake8-pyproject lets you put your config under a [tool.flake8] section and either keeps working with the normal flake8 command or gives you a flake8p entry point:

[tool.flake8]
max-line-length = 88
extend-ignore = ["E203"]
exclude = [".git", " __pycache__", "build", "dist"]

There is also pyproject-flake8 (the pflake8 command), which monkey-patches flake8 to read the file. Both work. I lean toward Flake8-pyproject because it is the lighter touch, but understand that either one is a workaround layered on top of a tool that, by design, still does not natively support the format.

How do you silence a specific warning inline?

Add a # noqa comment to the line, and be specific about which code you are silencing. flake8 gives you two forms, and the difference matters.

A bare # noqa silences every error on that line:

import os # noqa

A coded # noqa: E501 silences only that check. Anything else on the line still gets reported, which is exactly what you want:

url = "https://example.com/a/very/long/path/that/breaks/the/line/limit" # noqa: E501

You can list several codes with commas, like # noqa: E731,E123, and the comment is case-insensitive. I always prefer the coded form. A bare # noqa is a blunt instrument that hides real bugs the day someone adds a second problem to that line. If you ever need to audit what your # noqa comments are actually hiding, run with --disable-noqa and flake8 reports everything as if the comments were not there.

How do you run flake8 in pre-commit and CI?

Wire flake8 into pre-commit so it runs before code ever reaches a branch. The official hook is published in the flake8 repo, and the setup is a few lines in .pre-commit-config.yaml:

- repo: https://github.com/pycqa/flake8
    rev: 7.3.0
    hooks:
    - id: flake8

The docs show rev: '' as a placeholder, but always pin it to a real tag like 7.3.0. An unpinned linter version means your CI can start failing on a Tuesday because a new release added a check, and nobody changed a line of code. For CI itself, there is nothing special to configure. The same flake8 . command that runs locally runs in a GitHub Actions step, reads the same config file, and exits non-zero on any violation. If you are hardening a pipeline, the same discipline I described in enabling npm trusted publishing with OIDC applies here: pin your tool versions and let the config file be the single source of truth.

Which flake8 plugins are worth adding?

Plugins extend flake8 with new checks under their own code prefixes, and installing one is just a pip install into the same environment. Most start reporting immediately, no config required. You can confirm what loaded by running flake8 --version, which lists every active plugin.

The ones I reach for most:

flake8-bugbear (prefix B) catches likely bugs and questionable design that pyflakes misses, like mutable default arguments.
flake8-comprehensions (C4) flags list and dict comprehensions that could be simpler.
flake8-docstrings (D) checks PEP 257 docstring conventions by wrapping pydocstyle.
pep8-naming (N) enforces naming conventions for classes, functions, and variables.
flake8-bandit adds security checks, and flake8-comprehensions and flake8-simplify clean up common code smells.

Once a plugin is installed, its codes behave like any other. Turn them on or off with select, ignore, extend-select, and extend-ignore in your config. That is the real strength of flake8: the checker set is yours to compose.

Should you still use flake8 in 2026?

Use flake8 if you depend on a plugin Ruff has not reimplemented. Otherwise, Ruff is probably the better default. That is the honest answer, and it comes straight from Ruff's own documentation rather than my opinion.

Ruff is a linter written in Rust that advertises being "10-100x faster than existing linters (like Flake8)." Its FAQ is refreshingly precise about compatibility. Ruff is a drop-in replacement for flake8 when you use it without many plugins, alongside Black, on Python 3 code. Under those conditions it "implements every rule in Flake8," including all the pyflakes F rules and a large subset of the E and W style rules.

But Ruff names its own limit clearly: "Ruff's primary limitation vis-a-vis Flake8 is that it does not support custom lint rules." That is the line that keeps flake8 alive. If your team relies on an internal flake8 plugin, or a niche community one Ruff has not ported, flake8 is still the tool that can run it. The same goes for a stable, working setup where migration churn buys you nothing. Speed is real, but a linter you have already tuned and trust has value too.

I have migrated projects to Ruff and kept others on flake8, and both calls were right for their context. The mistake is treating it as a moral question. Pick the tool that runs the checks you need, and let the benchmark difference decide only when the checks are equal.

For the details behind everything here, see the flake8 documentation, the still-open pyproject.toml discussion in issue #234, and Ruff's FAQ on flake8 compatibility.

Keep Reading

How to Enable npm Trusted Publishing with GitHub Actions OIDC. Another piece of a hardened CI pipeline, where pinned tool versions matter just as much.
How to Check Out Fork PRs Safely in actions/checkout v7. Running linters on untrusted pull requests without opening a security hole.
How to Serve a React SPA from FastAPI with app.frontend(). More practical Python tooling, this time on the web-serving side.

HTTP QUERY Method: The Safe GET With a Body (RFC 10008)

Rabinarayan Patra — Thu, 02 Jul 2026 18:30:00 +0000

Every REST API I have ever worked on grows a POST /search endpoint sooner or later. Not because POST is the right method for reading data, but because GET cannot carry a request body and the filter JSON stopped fitting in the URL years ago. As of mid-June 2026, HTTP finally has a proper fix. It is called QUERY, and it just became RFC 10008.

The HTTP QUERY method gives you the thing GET and POST each refuse to: a safe, idempotent, cacheable request that carries a body. In this post I will walk through what the spec actually says, why GET-with-a-body and POST-for-reads are both broken, how caching works when the cache key lives in the request body, and which runtimes you can use it on today.

What is the HTTP QUERY method?

The HTTP QUERY method is a new request method, standardized in RFC 10008 in mid-June 2026, that sends a query as the request body while keeping the guarantees of GET. The spec's abstract puts it well: "A QUERY requests that the request target process the enclosed content in a safe and idempotent manner and then respond with the result of that processing."

The body is the query. Not the resource, not a command, a question. "The content of the request and its media type define the query." That media type matters: the spec says servers MUST fail the request if Content-Type is missing or inconsistent with the content. A successful query comes back as a plain 200 OK with the results in the response body.

Here is the comparison table straight from Section 1 of the RFC:

Property	GET	QUERY	POST
Safe	Yes	Yes	Potentially no
Idempotent	Yes	Yes	No
Cacheable	Yes	Yes	Only for future GET or HEAD requests
Request body	No defined semantics	Expected	Expected

There is also a discovery mechanism. A server can advertise QUERY support with the new Accept-Query response header, a Structured Field listing the query media types it accepts for that path:

Accept-Query: "application/jsonpath", application/sql;charset="UTF-8"

The RFC was written by Julian Reschke (greenbytes), James M. Snell (Cloudflare), and Mike Bishop (Akamai), and it is a Proposed Standard on the IETF standards track. This is not a vendor experiment. It is the real thing.

Why isn't GET with a body enough?

Sending a body with GET is undefined behavior that some servers and intermediaries will actively reject. RFC 9110, the core HTTP semantics spec, is blunt about it in Section 9.3.1: "content received in a GET request has no generally defined semantics, cannot alter the meaning or target of the request, and might lead some implementations to reject the request and close the connection because of its potential as a request smuggling attack."

So the standard advice has always been: put the query in the URL. That works until it does not. RFC 9110 only recommends that implementations support URIs of at least 8,000 octets, and that is a floor, not a promise. Real limits vary per proxy, per load balancer, per server, and you discover the smallest one in the chain at runtime. The spec for the 414 status code even names the workaround as the culprit: it happens "when a client has improperly converted a POST request to a GET request with long query information."

I have debugged exactly one 414 in my career and it cost me most of a day, because the request worked fine locally and only failed behind a corporate proxy with a tighter URI limit. That is the nature of this failure: it is environmental, and your test suite will not catch it.

RFC 10008's introduction lists two more problems with query-in-the-URL that I find underrated. First, URLs leak: "request URIs are more likely to be logged than request content and may also turn up in bookmarks." If your query contains anything sensitive, it is now in every access log along the path. Second, my favorite line in the whole spec: encoding queries into the URI "effectively casts every possible combination of query inputs as distinct resources." Your cache and your metrics now treat ?city=Berlin&limit=50 and ?limit=50&city=Berlin as different things, even though they are the same question.

Why not just use POST for queries?

POST works for queries right up until you need retries, caching, or honest semantics. The problem is not that POST fails. It is that POST tells every piece of HTTP infrastructure to assume the worst.

POST is not safe and not idempotent. When a connection drops mid-request, neither the client nor any proxy can know whether state changed on the server. So nothing retries automatically. Compare that with the QUERY abstract: QUERY requests "can be automatically repeated or restarted without concern for partial state changes." For genuinely unsafe operations you end up building retry safety by hand, which is exactly the machinery I covered in idempotency keys for REST APIs. Reads should never have needed that machinery in the first place.

And then there is caching. RFC 9110 Section 9.3.3 allows caching POST responses only when the response carries explicit freshness information plus a Content-Location that matches the target URI, and even then the cached response can only serve future GET and HEAD requests. It says directly: "a POST request cannot be satisfied by a cached POST response because POST is potentially unsafe." Two identical POST /search calls always hit your origin. Every dashboard that polls a search endpoint is doing full-price origin work on every tick.

QUERY flips all three defaults. Safe, so infrastructure can retry it. Idempotent, so retries need no bookkeeping. Cacheable, so identical questions can be answered without recomputing.

How does caching work for QUERY requests?

A QUERY response is cacheable, but the cache key must include the request content, not just the URI. That is the core trade the spec makes, and Section 2.7 is explicit: the cache key "MUST incorporate the request content" and related metadata.

This is genuinely harder than caching GET. The spec admits it: "caching QUERY method responses is inherently more complex than caching responses to GET, as complete reading of the request's content is needed in order to determine the cache key." A cache has to buffer the body before it can even decide whether it has seen this request before.

To avoid trivial misses, caches are allowed to normalize: they "MAY remove semantically insignificant differences from request content." The spec calls out stripping content encodings and using media type suffix knowledge, like treating anything ending in +json as JSON for normalization purposes. The flip side lands in the security section: normalize too aggressively and "normalization results in a false positive," meaning a cache can hand back the wrong query's results. If you build or configure a QUERY-aware cache, that is the failure mode to fear.

Conditional requests work too, through a clever indirection the spec calls the equivalent resource: a hypothetical GET-able resource derived by incorporating the request content into the target. Your ETag and If-None-Match validators operate against that, so a repeated query can come back 304 Not Modified.

Two response headers round out the model, and they are easy to confuse:

Content-Location points at the query results, a URI you can plainly GET later to retrieve the same representation.
Location points at the query itself, a URI that re-runs the query on GET without resending the body.

One redirect trap worth knowing: the historical browser behavior of rewriting a redirected POST into a GET does not apply here. The spec states the 301/302 exceptions for POST do not apply to QUERY. Only a 303 tells the client to fetch the result with GET.

Why was it named QUERY instead of SEARCH?

The spec spent its first six years named SEARCH and dropped the name to escape WebDAV baggage. The idea goes back to a 2015 individual draft (draft-snell-search-method), got revived by Asbjorn Ulsberg at the HTTP Workshop in 2019, and was adopted by the httpbis working group in March 2021, still called SEARCH.

The rename happened in November 2021. Appendix B of the RFC explains the reasoning with unusual candor. The IANA method registry already had three safe, idempotent methods: PROPFIND, REPORT, and SEARCH. All three come out of the WebDAV effort, "about which many have mixed feelings," and all use generic XML request formats. QUERY got a clean start, and as the appendix notes, the name "captures the relation with the URI's query component well."

From there it was a slow march: final draft in November 2025, IESG approval on November 20, 2025, and publication as RFC 10008 in mid-June 2026. Eleven years from first draft to standard. HTTP does not move fast, which is exactly why it is worth paying attention when it does move.

Who supports the HTTP QUERY method in 2026?

Node.js has parsed QUERY natively since early 2024, OpenAPI 3.2 can document it, and Spring's support is an open pull request. Here is the honest state of things as of July 2026:

Stack	Status (July 2026)
Node.js	Native. QUERY parsing landed via llhttp 9.2.0 in Node 21.7.2 and Node 22+
Express	Works on QUERY-capable Node, but no TypeScript types yet
Fastify	Opt-in: `fastify.addHttpMethod('QUERY', { hasBody: true })`
Go net/http	No `MethodQuery` constant, but arbitrary method strings work today
Spring Framework	Not shipped. PR #34993 is open and currently labeled blocked
ASP.NET Core	.NET 11 Preview 4 maps QUERY and emits it in OpenAPI output
OpenAPI	3.2.0 (September 2025) added a first-class `query` operation field
curl	Generic `-X QUERY` with `--data` and an explicit `Content-Type`
Browsers (fetch)	Accepted as a method string, but always triggers a CORS preflight

A few of these deserve context. The Spring situation is the one I am watching closest as a Java developer: the original issue (#32975) sat for two years and was superseded by PR #34993, which the author marked ready for review the same week the RFC published. As of early July 2026 the RequestMethod enum still has no QUERY, so Spring apps cannot route it through @RequestMapping yet.

On the browser side, QUERY is not a CORS-safelisted method, and the RFC says plainly that a cross-origin QUERY "will require a preflight request." Budget for the extra OPTIONS round trip, and if preflights have bitten you before, my Spring Boot CORS guide covers how to configure them properly. MDN has no QUERY page yet and there is no caniuse entry, which tells you how early we still are.

And do not assume CDN support. Two of the RFC's three authors work at Cloudflare and Akamai, which bodes well, but I could not find any announcement from either that their edge caches handle QUERY today.

How can you try the QUERY method today?

curl plus Node 22 is enough to build a working QUERY endpoint right now, no dependencies required. curl sends any method you give it:

curl -X QUERY 'http://localhost:3000/contacts' \
  -H 'Content-Type: application/json' \
  -d '{"filter": {"city": "Berlin"}, "limit": 50}'

On the server side, Node's HTTP parser accepts QUERY natively, so req.method just works:

import { createServer } from 'node:http';

const server = createServer((req, res) => {
  if (req.method !== 'QUERY') {
    res.writeHead(405, { Allow: 'QUERY' });
    res.end();
    return;
  }

  let body = '';
  req.on('data', (chunk) => (body += chunk));
  req.on('end', () => {
    const query = JSON.parse(body);
    // Run the actual search here. The body IS the query.
    res.writeHead(200, { 'Content-Type': 'application/json' });
    res.end(JSON.stringify({ query, results: [] }));
  });
});

server.listen(3000);

From a browser or any JavaScript runtime, fetch takes QUERY as a plain method string:

const res = await fetch('http://localhost:3000/contacts', {
  method: 'QUERY',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ filter: { city: 'Berlin' }, limit: 50 }),
});

const { results } = await res.json();

Remember the preflight: cross-origin, this fires an OPTIONS request first, every time, because QUERY is not safelisted.

If you are on Spring, you are stuck waiting or working around. Since RequestMethod does not know QUERY, requests with the method never reach your controllers through normal mapping. A servlet filter registered ahead of Spring MVC can intercept "QUERY".equals(request.getMethod()) and dispatch manually, but I would treat that as a stopgap and keep an eye on PR #34993 instead.

Should you adopt QUERY now?

For internal services on Node, I would start using QUERY today. The parser support is there, the semantics are standardized, and internal traffic does not care about CDN or browser maturity. Every retry policy and cache layer you control can start taking advantage of safe-and-idempotent reads immediately.

For public APIs, advertise before you commit. Ship Accept-Query on endpoints that support it, keep the POST variant alive for older clients, and let OpenAPI 3.2 document both. The tooling wave is coming from an interesting direction: with OpenAPI 3.2 and ASP.NET 11 both recognizing QUERY, generated clients will start offering it before most hand-written servers do.

The 420-point Hacker News thread that greeted the RFC in June 2026 suggests developers have been waiting for this one. I think POST /search will read as a legacy idiom within a few years, the same way X- headers do now. The method finally matches the meaning.

For the primary sources, read RFC 10008 itself, the HTTP semantics it builds on in RFC 9110, and the OpenAPI 3.2.0 announcement that added first-class QUERY support.

Keep Reading

How to Implement Idempotency Keys in REST APIs the Right Way. QUERY gives reads the retry safety that writes still have to build by hand.
Solving Spring Boot CORS Errors Once and For All. Every cross-origin QUERY triggers a preflight, so get your CORS config right first.
How to Version REST APIs in Spring Framework 7 (Spring Boot 4). More API design decisions in the current Spring generation.

iOS 27 for Developers: Breaking Changes and New APIs

Rabinarayan Patra — Tue, 23 Jun 2026 18:30:00 +0000

Apple announced iOS 27 at the WWDC keynote on June 8, 2026, and the developer betas went out the same week. Most of the coverage you've seen is about Liquid Glass getting prettier and Siri getting smarter. That's the consumer story. The developer story is sharper: open your project in Xcode 27, hit build, and a couple of things that used to be warnings are now hard failures.

I went through the iOS 27 beta release notes, the developer documentation, and Apple's own developer newsroom posts to pull out what actually matters when you compile. This is a developer spec, not a feature reel. We'll cover the breaking changes that can reject your app, the deprecations you should start migrating off, the new design rules you can no longer skip, and the genuinely interesting new frameworks (Core AI, Foundation Models, and a pile of smaller ones). Where Apple has not committed to something publicly, I'll say so instead of guessing.

When does iOS 27 ship and what do you build it with?

iOS 27 ships in the usual rhythm: betas now, public beta in July, and general release expected in September 2026, though Apple has not published an exact date. The whole family moved together, so iPadOS 27, macOS 27, watchOS 27, tvOS 27, and visionOS 27 all landed at the same keynote.

The toolchain is where the practical facts are. iOS 27 builds with Xcode 27 , which bundles the iOS and iPadOS 27 SDK and runs the Swift 6.4 compiler. Two things about Xcode 27 are worth knowing before you download it: it's Apple-silicon only now (Intel Macs can't run it), and the install is about 30% smaller than Xcode 26.

Here's the part that saves you from panic: there is no deadline forcing you onto the iOS 27 SDK yet. Apple's submission floor is still the iOS 26 SDK with Xcode 26, which became mandatory on April 28, 2026. The "Upcoming Requirements" page lists nothing past that. So you don't have to ship against iOS 27 in a hurry. You should still test against it early, because the breaking changes below are easier to fix in June than in a September release scramble.

What breaks when you recompile against the iOS 27 SDK?

Two changes are hard gates that stop your app cold, and a few more are quieter source-level breaks. Start with the two that matter most, because they're the ones that turn a routine recompile into a rejected build or a crash on launch.

First, a launch screen is now required. Apps built with the 27.0 SDK must declare one of UILaunchScreen, UILaunchStoryboardName, UILaunchScreens, or UILaunchStoryboards in Info.plist, or the App Store rejects the upload. Second, the scene-based lifecycle is now required. If your app still boots through the old app-based lifecycle without a scene manifest, it fails to launch on iOS 27.

If you've been putting off scene adoption, this is the forcing function. The fix is a UIApplicationSceneManifest in your Info.plist and a UIWindowSceneDelegate:

<key>UIApplicationSceneManifest</key>
<dict>
  <key>UIApplicationSupportsMultipleScenes</key>
  <true/>
  <key>UISceneConfigurations</key>
  <dict>
    <key>UIWindowSceneSessionRoleApplication</key>
    <array>
      <dict>
        <key>UISceneConfigurationName</key>
        <string>Default Configuration</string>
        <key>UISceneDelegateClassName</key>
        <string>$(PRODUCT_MODULE_NAME).SceneDelegate</string>
      </dict>
    </array>
  </dict>
</dict>

The next one bites SwiftUI code. @State is now a macro. Apple calls it source-compatible "with exceptions," and the exceptions are real. You can no longer set an initial value both at the declaration and in init (the init value gets discarded), the auto-synthesized init is disabled for private members using @State, generic inference is weaker, and @State won't compose with other property wrappers. So this pattern stops doing what you think:

struct CounterView: View {
    @State private var count = 0 // declaration value

    init(startingAt count: Int) {
        _count = State(initialValue: count) // discarded under the macro
    }
    // ...
}

There's also a cluster of UIKit changes. UIApplication.statusBarFrame, statusBarOrientation, statusBarStyle, and isStatusBarHidden are deprecated and can now return NaN or null, so read from the window scene instead:

// Deprecated in iOS 27
let style = UIApplication.shared.statusBarStyle

// Use the scene's status bar manager
let style = view.window?.windowScene?.statusBarManager?.statusBarStyle

A few more to scan for: menu item images are hidden by default on iPadOS and macOS 27 (set preferredImageVisibility on UIMenuElement to bring them back), UISearchController center placement now renders the scope bar inline with the search field, and UIKit presentation trait inheritance now walks the superview chain instead of jumping to the presentation controller, so custom UIPresentationController subclasses may need a look.

Which APIs and frameworks are deprecated in iOS 27?

Three deprecations are worth acting on now, even though none of them break your build today. Deprecations are free to ignore until the year they aren't, and these all have clean replacements already shipping.

Deprecated	Replacement	Why it matters
On Demand Resources, `NSBundleResourceRequest`	Background Assets	ODR is the old way to stage large assets. Background Assets is the supported path going forward.
Original MetricKit (`MXMetricManager`, `MXMetricPayload`, `MXDiagnosticPayload`)	`MetricManager`	If you collect launch time, hang rate, or crash diagnostics, move to the new manager.
`UIApplication` status-bar accessors	`UIWindowScene.statusBarManager`	Covered above. Also formally deprecated, not just discouraged.

There's one Swift toolchain trap that isn't a framework deprecation but will waste your afternoon if you hit it. Swift 6.4 adds new stat() instance methods on FilePath and FileDescriptor. If you wrote your own extensions that call an unqualified stat(), the call can now resolve to the wrong thing. Disambiguate with Darwin.stat().

On the security side, iOS 27 tightens TLS in a set of system processes (MDM, declarative device management, Automated Device Enrollment, profile install, app install, and software updates). Those servers now need to support TLS 1.2 minimum with App Transport Security compliant cipher suites and certificates, or the connections fail. If you run enterprise device management infrastructure, this is the line item to verify before your fleet updates.

What is Liquid Glass and why can't you opt out anymore?

Liquid Glass is Apple's system design language from iOS 26, and in iOS 27 it's refined rather than renamed, with one change that affects every app: you can no longer opt out. iOS 26 shipped a temporary Info.plist key that let apps keep the old look while they adapted. iOS 27 removes that escape hatch. Any app recompiled with Xcode 27 automatically adopts the new design.

What "refined" means in practice: refreshed system materials, updated typography, and reworked tab bars and navigation bars. App icons render sharper automatically, and users get a transparency slider in Settings to tune the effect. None of that is opt-in. So if your layout leaned on the old material blur or assumed specific bar metrics, test it against the beta now.

There's a second design change that's easy to miss because it sounds like a feature: iOS apps are now resizable , both on large iPad displays and through iPhone Mirroring on the Mac. Resizable means your layout has to respond to live size changes, not just rotation. If you have hard-coded frames or assumed a fixed width, this is the moment that breaks. It's the same discipline good adaptive layouts already follow, but iOS 27 makes it non-optional for more surfaces.

What can you build with Core AI and the Foundation Models framework?

iOS 27 splits on-device AI into two layers: Foundation Models is the high-level Swift API for generating content, and Core AI is the lower-level framework for running your own models. They're different tools, and the distinction matters when you decide what to build.

Foundation Models is now a single Swift generation API that spans the on-device system language model, Private Cloud Compute models, Core AI, and MLX, plus third-party providers through a new Language Model protocol. In iOS 27 it adds image input (so it's multimodal), server model support, and Dynamic Profiles, which let you swap the model, tools, or instructions mid-session. Apple also said the framework is going open source later in summer 2026, with the same Swift APIs running server-side. The basic shape is the same friendly session you may have seen in iOS 26:

import FoundationModels

let session = LanguageModelSession()
let reply = try await session.respond(
    to: "Summarize this support ticket in one sentence."
)
print(reply.content)

Guided generation still uses the @Generable macro to get typed structs back instead of parsing strings, and tool calling lets the model invoke your functions (including on-device Vision tools like OCR and barcode reading). The exact signatures are still moving during beta, so check the current docs before you wire anything load-bearing.

Core AI is the bring-your-own-model path. It's built into the OS, tuned for Apple silicon, and lets you load, specialize, and run custom models fully on-device with ahead-of-time compilation. Apple ships Python tools to convert PyTorch models to Apple silicon, and Core AI is what powers the new on-device Siri under the hood. If you've been running a model through a third-party runtime to keep it on-device, this is the native option.

One pricing fact that's genuinely useful: developers in the Small Business Program (under 2 million lifetime first-time downloads) get the next-generation Apple Foundation Models on Private Cloud Compute at no cloud API cost. That's a real lever for indie and small-team apps that want server-grade inference without a per-token bill. If you've been comparing this with wiring up your own model router, my take on Claude Skills vs MCP vs Projects covers how to think about where the model logic should live.

What new frameworks ship in iOS 27 beyond AI?

Plenty, and several are the kind of thing you'd otherwise build yourself. Here are the ones worth knowing about, grouped by what they do.

Evaluations framework : validates AI feature behavior across changing conditions, going beyond unit tests. If you ship anything model-driven, this is how Apple wants you to test it.
App Intents Testing framework : validates App Intents through real system pathways without UI automation, which has been a pain point for years.
App Intents (expanded): adds entity schemas that contribute content to the Spotlight semantic index, intent schemas for natural-language actions without predefined phrases, and a View Annotations API that maps views to entities so Siri can reference what's on screen.
Music Understanding framework : analyzes audio across six dimensions on-device.
NowPlaying framework : connects your app's playback to the Lock Screen, Control Center, Dynamic Island, and CarPlay through one API.
SwiftUI additions : reorderable containers (drag to reorder across lists and grids), document-based apps with direct disk access, lazily loaded subviews that prefetch for smoother scrolling, and a Spatial Preview framework for 3D model viewing.
WidgetKit : widgets are now customizable through App Intents with dynamic styling.
Image Playground API : the generative model is reimagined on Private Cloud Compute and can produce photorealistic images in-app.

App Intents is the one I'd prioritize. It's the connective tissue between your app and Siri's new personal context and on-screen awareness, and the entity and intent schemas are how your content shows up in places you don't control directly.

How does Xcode 27 change your build and test loop?

Xcode 27 changes two habits: the Simulator is gone, and coding agents are built in. The first is structural. Device Hub replaces the Simulator , unifying virtual and physical devices in one place so you diagnose and reproduce issues across both from inside the IDE. If your scripts or CI reference the Simulator by name, that's a migration to plan.

The second is the agentic coding story. Xcode 27 integrates agents from Anthropic, Google, and OpenAI that can run your tests, run the app in the new Device Hub, try code in a Playground, pull a crash from the Organizer and fix it, and localize your app. It's extensible too, through plugins and MCP tools and the Agent Client Protocol, with GitHub and Figma as first-party plugin installs. There's also an fm command-line tool and a Python SDK for scripting Foundation Models outside the app. If you already work with CLI coding agents, the best Claude skills for developers translate cleanly to this workflow.

The smaller quality-of-life wins add up: iCloud settings sync so your Xcode setup follows you across Macs, a fully customizable toolbar, app-wide color themes, faster project loads, and Xcode Cloud builds up to twice as fast. Apple also mentioned that parts of the OS kernel are now written in Swift, which is more of a milestone than a developer-facing API, but it tells you where the platform is heading.

Should you adopt iOS 27 now or wait?

Wait to ship against it, but test against it this week. Since there's no deadline forcing the iOS 27 SDK, you don't need to rush a release. But the two hard build gates (launch screen and scene-based lifecycle) plus the @State macro change are exactly the kind of thing that's a calm afternoon now and a fire drill the week of general release. Pull the beta, recompile, and fix the build failures while there's no pressure.

The more interesting question is what iOS 27 unlocks. Core AI plus free Private Cloud Compute for small developers is the first time running real models, on-device or server-side, is a default capability instead of a research project. If you've been waiting for a reason to put a model in your app without a cloud bill, this is it. The breaking changes are the cost of entry. The AI frameworks are why you'd want to pay it.

For the primary details, see Apple's iOS 27 what's new for developers, the iOS and iPadOS 27 release notes, and Apple's developer newsroom post on the new intelligence frameworks and tools.

Keep Reading

Branch.io Deep Linking and Mobile Attribution Explained. The mobile-growth side of shipping apps, once your iOS 27 build is clean.
Claude Skills vs MCP vs Projects: Which One Should You Use?. Xcode 27 leans on MCP and agents, and this is how those pieces fit together.
10 Best Claude Skills for Developers in 2026. Practical agent workflows that map onto Xcode 27's new agentic coding.

How to Migrate Vercel AI SDK 5 to 6: Breaking Changes Guide

Rabinarayan Patra — Tue, 16 Jun 2026 18:30:00 +0000

Vercel shipped AI SDK 6 on May 7, 2026. It is the biggest breaking-change release the SDK has shipped since the 3.0 split. The v3 Language Model Specification, a real Agent abstraction, human-in-the-loop tool approval, a unified message-parts model on useChat, and a new streaming wire format all landed in the same drop.

I migrated the AI chatbot on this portfolio over the weekend. The codemod did most of the mechanical work, but four spots needed hand edits. This post walks the migration the way I ran it, with the exact code diffs that broke and the verification steps that confirmed the migration shipped without a silent UX regression.

What changed in Vercel AI SDK 6?

AI SDK 6 ships the v3 Language Model Specification, the Agent interface with ToolLoopAgent as the production implementation, a unified message-parts array on useChat, an OAuth-ready MCP client, reranking, image editing, and a new streaming wire format that pairs naturally with Suspense and loading.tsx for a 15 to 25 percent first-token latency win on cold-start route invocations. The Vercel post calls the wire format change "the foundation for several capabilities Vercel has been signposting for the second half of 2026".

The four breaking-change axes that affect existing apps are:

Axis	What broke	Where you fix it
useChat message-parts	Messages no longer carry a flat `content` string. They carry a `parts` array of typed entries.	Every React component that renders `message.content`
Tool-call streaming lifecycle	Tool calls now flow through explicit `state` transitions (`input-streaming`, `input-available`, `output-available`, `approval-requested`).	Tool render switch statements in your UI
Provider-adapter contract	The v3 Language Model Specification changes how provider packages expose tools, finish reasons, and usage details.	Custom provider wrappers and middleware
Streaming wire format	New ordering and chunk types for tool calls and reasoning traces.	Anything that reads the SSE stream directly

The codemod handles the easy half. The other half is where this guide focuses.

Which breaking changes hit you first?

The useChat parts model is the change that hits you first because it is silent. Your app keeps compiling. Your messages array keeps populating. But the moment a tool gets invoked, the tool-call UI never renders, because your code is still reading message.content and the tool call now lives in message.parts.

I caught this in my own portfolio because the AI chat that answers questions about my blog posts uses one tool (search_blog_posts). After upgrading, the chat worked perfectly for plain prompts and dropped the search-result card entirely for tool prompts. No console error, no broken request. Just a missing block in the UI.

The second-hardest break is streamText callers that built their own agent loop with stopWhen and a step counter. The v6 way is ToolLoopAgent, and the two cannot be mixed in a single component because they emit different stream shapes.

The third break is the wire format. If you parse the SSE stream by hand anywhere in your codebase, you have to rewrite that parser. Most apps do not, but server-rendered chat UIs and custom telemetry layers usually do.

How do you run the codemod the right way?

You run the codemod by pinning the SDK version first, running the official transform from a clean working tree, then reviewing every changed file before you let it land. Treat the codemod output as a starting point, not a finished migration.

# 1. Pin both packages at the v6 line. Do this before running the codemod.
npm install ai@6 @ai-sdk/openai@6 @ai-sdk/anthropic@6

# 2. Confirm a clean git status. The codemod will rewrite files in place.
git status

# 3. Run the official codemod from the repo root.
npx @ai-sdk/codemod upgrade v6

# 4. Inspect the diff.
git diff --stat
git diff src/app

The codemod prints a summary of files touched. On the chatbot in this portfolio it rewrote 9 files: the route handler, the chat component, and seven smaller utilities. It did not touch my custom tool renderer or the route that streams blog embedding search results, because both rely on shapes that the codemod cannot infer.

If the diff looks plausible, commit it as a separate commit before touching anything else. That gives you a clean rollback point.

git add -A
git commit -m "chore(ai-sdk): apply v6 codemod automated changes"

Now you can start the hand edits on top of a known-good base.

How do you migrate useChat to message parts?

You migrate useChat by rewriting every render path that reads message.content to walk message.parts and switch on part.type. The new model treats text, tool calls, tool results, and reasoning traces as first-class entries that all live in the same array.

Here is the before and after on the simplest possible chat component.

v5 style (broken in v6 the moment a tool fires):

'use client'
import { useChat } from 'ai/react'

export function Chat() {
  const { messages, input, handleSubmit, handleInputChange } = useChat()

  return (
    <div>
      {messages.map((m) => (
        <div key={m.id}>
          <strong>{m.role}:</strong> {m.content}
        </div>
      ))}
      <form onSubmit={handleSubmit}>
        <input value={input} onChange={handleInputChange} />
      </form>
    </div>
  )
}

v6 style with the parts model:

'use client'
import { useState } from 'react'
import { useChat } from 'ai/react'
import type { WeatherAgentUIMessage } from '@/agents/weather-agent'

export function Chat() {
  const { messages, sendMessage } = useChat<WeatherAgentUIMessage>()
  const [input, setInput] = useState('')

  const onSubmit = (event: React.FormEvent) => {
    event.preventDefault()
    if (!input.trim()) return
    sendMessage({ text: input })
    setInput('')
  }

  return (
    <div>
      {messages.map((m) => (
        <div key={m.id}>
          <strong>{m.role}:</strong>
          {m.parts.map((part, i) => {
            switch (part.type) {
              case 'text':
                return <span key={i}>{part.text}</span>
              case 'tool-weather':
                return <WeatherCard key={i} invocation={part} />
              case 'reasoning':
                return <Reasoning key={i} trace={part.text} />
              default:
                return null
            }
          })}
        </div>
      ))}
      <form onSubmit={onSubmit}>
        <input value={input} onChange={(e) => setInput(e.target.value)} />
      </form>
    </div>
  )
}

Three things make this work. First, useChat<WeatherAgentUIMessage>() infers the typed part union from your agent definition. The exported InferAgentUIMessage<typeof weatherAgent> is what you import as WeatherAgentUIMessage. Second, handleSubmit and handleInputChange are gone in v6. You manage the input state yourself and call sendMessage({ text }) to submit. Third, you need a default fallback in the switch. If you forget it and the agent introduces a new part type, the UI silently drops that block at runtime.

After this change, both the plain-text path and the typed tool-weather path render. The Vercel migration playbook calls this "the silent UX regression" and recommends adding a unit test that asserts every part type your agent emits has a render case.

How do you replace streamText with ToolLoopAgent?

You replace streamText by extracting the loop configuration into a ToolLoopAgent instance and calling .stream() or .generate() on it. The agent holds the model, instructions, tools, and stop condition once, and you reuse it everywhere from chat routes to background jobs to standalone scripts.

The before and after on a typical route handler looks like this.

v5 route handler:

// app/api/chat/route.ts
import { streamText } from 'ai'
import { openai } from '@ai-sdk/openai'
import { weatherTool } from '@/tools/weather'

export async function POST(req: Request) {
  const { messages } = await req.json()

  const result = await streamText({
    model: openai('gpt-4o'),
    system: 'You are a helpful weather assistant.',
    messages,
    tools: { weather: weatherTool },
    maxSteps: 20,
  })

  return result.toDataStreamResponse()
}

v6 route handler with ToolLoopAgent:

// agents/weather-agent.ts
import { ToolLoopAgent, type InferAgentUIMessage } from 'ai'
import { weatherTool } from '@/tools/weather'

export const weatherAgent = new ToolLoopAgent({
  model: 'openai/gpt-5.4',
  instructions: 'You are a helpful weather assistant.',
  tools: {
    weather: weatherTool,
  },
})

export type WeatherAgentUIMessage = InferAgentUIMessage<typeof weatherAgent>

// app/api/chat/route.ts
import { weatherAgent } from '@/agents/weather-agent'

export async function POST(req: Request) {
  const { messages } = await req.json()

  const result = await weatherAgent.stream({ messages })
  return result.toUIMessageStreamResponse()
}

Three details matter on this migration. First, the plain provider-prefixed model string 'openai/gpt-5.4' routes through the Vercel AI Gateway by default, which is the pattern the Vercel knowledge update calls out as the recommended path. The gateway gives you per-request usage tracking, failover across providers, and zero data retention. The v5-era pattern of importing the provider package and calling openai('...') still works, but the string form is shorter and is what new code should use.

Second, toUIMessageStreamResponse is the v6 name for what used to be toDataStreamResponse. The codemod renames it most of the time. Check the route handlers.

Third, stopWhen lives on the agent now, not on the call. The default is 20 steps. If you used to pass maxSteps: 5 everywhere, set stopWhen: stepCountIs(5) on the agent constructor.

I wired the same pattern into the Vercel AI Gateway deep dive on this site. The shape is identical for Claude ('anthropic/claude-sonnet-4.5') and for any other provider in the gateway catalog.

How do you wire human-in-the-loop tool approval?

You wire approval by adding a needsApproval predicate to the tool and rendering an approval-requested state in the UI. The agent pauses, the UI shows the approval prompt, and the user accepts or rejects before the tool actually runs.

The tool side looks like this.

// tools/run-command.ts
import { tool } from 'ai'
import { z } from 'zod'

export const runCommand = tool({
  description: 'Run a shell command on the user machine',
  inputSchema: z.object({
    command: z.string().describe('The shell command to execute'),
  }),
  needsApproval: async ({ command }) => command.startsWith('rm '),
  execute: async ({ command }) => {
    const { stdout } = await execCommand(command)
    return { stdout }
  },
})

The UI side adds a render case for the new state.

case 'tool-runCommand': {
  if (part.state === 'approval-requested') {
    return (
      <div className="approval-prompt" key={i}>
        <p>Run: <code>{part.input.command}</code> ?</p>
        <button
          onClick={() =>
            addToolApprovalResponse({
              id: part.approval.id,
              approved: true,
            })
          }
        >
          Approve
        </button>
        <button
          onClick={() =>
            addToolApprovalResponse({
              id: part.approval.id,
              approved: false,
            })
          }
        >
          Reject
        </button>
      </div>
    )
  }
  if (part.state === 'output-available') {
    return <pre key={i}>{part.output.stdout}</pre>
  }
  return null
}

addToolApprovalResponse ships from the useChat return value. The agent resumes execution as soon as the approval message hits the stream. If the user rejects, the agent gets a structured rejection event and can recover or apologize.

The predicate runs on the server, so it can hit a policy service or an authorization check. That is the path I use to gate shell-style tools behind a per-account permission check. The same pattern would gate the more dangerous Anthropic and OpenAI provider tools (anthropic.tools.memory_20250818, openai.tools.shell) when those land in your stack.

How do you verify the migration before shipping?

You verify the migration by running the test suite, hitting every route that exercises tools, watching the DevTools timeline on a streaming chat, and replaying a representative production transcript against the new agent in a staging environment. If any of those four steps surfaces a regression, do not ship.

For the unit-test side, I added one test per agent that walks every expected part type.

// __tests__ /weather-agent.test.ts
import { describe, it, expect } from 'vitest'
import { weatherAgent } from '@/agents/weather-agent'

describe('weatherAgent', () => {
  it('emits text, tool-weather, and finish parts in order', async () => {
    const result = await weatherAgent.generate({
      prompt: 'What is the weather in San Francisco?',
    })

    const partTypes = result.messages
      .flatMap((m) => m.parts)
      .map((p) => p.type)

    expect(partTypes).toContain('text')
    expect(partTypes).toContain('tool-weather')
  })
})

For the DevTools verification, wrap the model in middleware and launch the viewer locally.

import { wrapLanguageModel } from 'ai'
import { devToolsMiddleware } from '@ai-sdk/devtools'
import { gateway } from 'ai'

const tracedModel = wrapLanguageModel({
  model: gateway('openai/gpt-5.4'),
  middleware: devToolsMiddleware(),
})

npx @ai-sdk/devtools
# http://localhost:4983

The DevTools viewer renders the full agent timeline: prompt, tool calls, tool results, model responses, and step boundaries. Use it once per migrated route. If a tool call shows up but the matching tool-* render case never fires in your UI, the parts switch is missing a case.

For staging replay, capture three representative production transcripts in your logs, run them through the new agent, and diff the response shape. The token usage breakdown is the cleanest signal because the v6 usage.inputTokenDetails and usage.outputTokenDetails are richer than v5.

If you write your own tools, this is the moment to add inputExamples and strict: true everywhere. They are cheap on the wire and they catch the dumbest tool-call regressions before they reach prod.

tool({
  description: 'Search blog posts',
  inputSchema: z.object({
    query: z.string().min(2),
  }),
  strict: true,
  inputExamples: [
    { input: { query: 'virtual threads' } },
    { input: { query: 'mcp protocol' } },
  ],
  execute: async ({ query }) => searchBlogPosts(query),
})

For deeper background on AI SDK patterns that the v6 Agent abstraction now formalizes, see the Vercel AI Gateway deep dive and the Claude Opus 4.7 release and migration guide.

For the original sources, see the AI SDK 6 announcement, the official migration guide, the ToolLoopAgent reference, and the Vercel AI SDK v5 to v6 migration playbook.

Keep Reading

Vercel AI Gateway Deep Dive. The provider routing layer that the v6 agent string format relies on, with cost and observability patterns.
Claude Opus 4.7 Release and Migration Guide. Provider-side context for the Anthropic models you plug into ToolLoopAgent.
Spring AI 2.0 MCP Annotations Tutorial. The same tool-loop pattern from the JVM side, and how the v6 MCP client connects both ends.
Replacing useEffect with Server Actions. The Next.js data-fetching shift that pairs with the v6 useChat parts model in App Router chat UIs.

10 Best Claude Skills for Developers in 2026

Rabinarayan Patra — Tue, 09 Jun 2026 18:30:00 +0000

Anthropic shipped Skills in October 2025. A year and a half later, the skill ecosystem is real. anthropics/skills has 141,849 stars. obra/superpowers has 209,283 stars. The open standard is live.

I install a lot of skills. Most do not earn the slot. These ten do. Quick-look format below: name, direct link, what it does, what I use it for. Ranked by impact in real work, with parent-repo star count as a popularity tiebreaker.

What are Claude Skills?

A Claude Skill is a folder with a SKILL.md file that teaches Claude one specific task. When the model sees a task that matches, it loads the skill and follows the playbook inside. The point is making behavior reliable. You write the convention once; every future session follows it.

Skills are generally available across claude.ai, Claude Code, and the Claude API (the API still requires the skills-2025-10-02 beta header).

How do you install Claude Skills?

Three install paths cover everything:

# Path 1: Anthropic official skills (clone into your skills folder)
mkdir -p ~/.claude/skills
cd ~/.claude/skills
git clone --depth 1 https://github.com/anthropics/skills.git anthropic-skills

# Path 2: superpowers plugin (run inside a Claude Code session)
/plugin install superpowers@claude-plugins-official

# Path 3: per-project skills (drop into .claude/skills/ in the repo root)

After install, restart your Claude Code session once.

What are the 10 best Claude skills for developers?

Ranked by impact, parent-repo stars listed for transparency.

1. brainstorming

Skill: obra/superpowers · brainstorming (parent repo 209k stars)
What it does: before any feature work, runs a structured exploration of intent, requirements, and design. Writes a short design memo. Asks for approval before any code.
Use it for: every "build X" or "add Y" request. Catches the one design question you forgot to ask.

2. systematic-debugging

Skill: obra/superpowers · systematic-debugging (209k stars)
What it does: forces a four-step bug protocol: reproduce deterministically, hypothesize root cause, prove or disprove with the smallest test, fix only the root cause.
Use it for: every flaky test and every "why is this slow?" investigation. Replaces try-catch reflex with real root-cause work.

3. test-driven-development

Skill: obra/superpowers · test-driven-development (209k stars)
What it does: writes the failing test first, runs it, shows the failure, then writes the implementation. Re-runs after each pass.
Use it for: any new function or feature where correctness matters. Stops Claude from "verifying" by re-reading its own code.

4. writing-plans

Skill: obra/superpowers · writing-plans (209k stars)
What it does: turns a vague request into a numbered plan with critical files identified, tradeoffs called out, and explicit checkpoints.
Use it for: any task that touches 3+ files or crosses a boundary (API, DB, infra). Prevents "looks done but breaks in three places."

5. executing-plans

Skill: obra/superpowers · executing-plans (209k stars)
What it does: runs a plan one step at a time in a separate session, with explicit checkpoints between steps.
Use it for: following up on a writing-plans output. Lets you resume mid-plan after a fix or a context switch.

6. subagent-driven-development

Skill: obra/superpowers · subagent-driven-development (209k stars)
What it does: spawns a subagent per independent subtask, runs them in parallel, merges results. Enforces clean handoff contracts.
Use it for: any task with parallelizable pieces (audit v1 vs v2 API, scan 5 services, compare 3 SDKs). Saves wall time and context budget.

7. verification-before-completion

Skill: obra/superpowers · verification-before-completion (209k stars)
What it does: runs the actual app or test suite end-to-end before reporting the task done. Surfaces evidence of what worked and what broke.
Use it for: the "tests pass but the feature is broken" class of bug. Pair with brainstorming + TDD for the full discipline loop.

8. skill-creator

Skill: anthropics/skills · skill-creator (parent repo 142k stars)
What it does: interviews you on trigger language, steps, and references, then writes a new SKILL.md in the right shape.
Use it for: every repeatable task you do more than twice a week. The meta-skill that pays for itself the first time.

9. graphify

Skill: safishamsi/graphify (55k stars)
What it does: runs an AST pass over your project, identifies god nodes, maps community structure, writes a queryable wiki under graphify-out/.
Use it for: any repo over 30k lines. Future sessions read the wiki instead of grep-walking the file tree.

10. mcp-builder

Skill: anthropics/skills · mcp-builder (parent repo 142k stars)
What it does: scaffolds an MCP server end-to-end (transport choice, tool annotations, auth, deployment hints). Generates a working Spring/Node/Python skeleton.
Use it for: the first MCP server you build. Replaces the "read 4 docs to get started" ritual with one prompt.

Which Claude skills should you install first?

Install in this order:

Run /plugin install superpowers@claude-plugins-official in Claude Code. Pulls 7 of the 10 skills above.
Clone anthropics/skills into ~/.claude/skills/anthropic-skills/. Gives you skill-creator, mcp-builder, and a wider base library.
Install safishamsi/graphify when your project crosses 30k lines.
Run skill-creator once. Build a custom skill for the most-repeated task in your current project. Writing one teaches you how to read others.

The thing nobody says out loud: the compounding only kicks in if you actually use them. Skills are habits, not features. Install one. Use it for two weeks. Then install the next.

For more on Claude Skills internals, see the Anthropic engineering deep-dive on agent skills, the Claude Code skills documentation, and the open skills standard at agentskills.io.

Keep Reading

Claude Skills vs MCP vs Projects. Where skills end and MCP servers begin.
Claude Code Routines: Async CI Automation Just Became Real. Use skills inside scheduled CI runs.
Claude Opus 4.7 Release and Migration Guide. The model these skills run on top of.

How to Set Up Sanity Studio in Next.js 16 (Embedded Dashboard)

Rabinarayan Patra — Thu, 04 Jun 2026 18:30:00 +0000

The default mental model for a headless CMS is two places: the CMS dashboard lives over there on the vendor domain, and your site lives over here on Vercel. Editors bounce between tabs, you copy environment variables between systems, and somebody always forgets to allowlist a domain in CORS.

Sanity does not require any of that. The Studio is a React app you ship inside your Next.js project. One catch-all route mounts the editor at /studio, your schemas live in TypeScript next to the rest of your code, and the whole thing deploys on the same Vercel push that ships your blog. This post walks through the full setup for Next.js 16: install, config, a real post + author + category schema, querying from a Server Component, the CORS fix every first-time user hits, and the Vercel deploy.

I built this exact integration into a small content site I run, and I will use that as the running example. If you already have a Next.js 16 app and want a working CMS dashboard inside it by the end of the next hour, you are in the right place.

What is Sanity Studio and why embed it in Next.js?

Sanity Studio is the editor UI that ships with Sanity, a hosted content platform that splits cleanly into two pieces: an open-source React app for editors, and a managed document store called the Content Lake. The Studio is the part you customize. The Lake is the part you query.

The reason to embed it in Next.js, instead of running it on the default sanity.studio subdomain, is that almost every project ends up wanting the same three things. Editors should sign in once on the same domain as the site. Schemas should live in TypeScript next to the components that render them. Deploys should be one Vercel push, not two. Embedding gets you all three for the cost of one catch-all route.

The latest stable release is sanity@5.30.0, with the official Next.js toolkit at next-sanity@13.0.11 as of June 2026. Both target the App Router and React 19, and Sanity migrated its own docs platform to Next.js 16 earlier this year, so the integration path is well-trodden.

What do you need before installing Sanity in Next.js 16?

You need a working Next.js 16 App Router project on Node 20 or newer, plus a free Sanity account. That is the entire prerequisite list.

Concretely:

Node 20+. The current Studio package drops support for Node 18 and 19. Check with node -v.
A Next.js 16 app on the App Router. Pages Router works too with a different route file, but this guide assumes App Router because that is what Next.js 16 starters default to.
A free Sanity account at sanity.io. The free tier gives you a project, a dataset, three editor seats, and 10k API requests per month, which is enough for a personal site.
A package manager. I use npm, but pnpm and yarn work without changes.

If you are starting from scratch, the rest of this guide assumes the same shape as a typical Next.js 16 app: a src/app directory, TypeScript on, Tailwind optional. The same steps apply if you keep app at the repo root.

How do you scaffold Sanity Studio inside an existing Next.js app?

Run npx sanity@latest init at the root of your Next.js project, then install the Next.js bridge package separately. The init command creates the Sanity project on the server, writes a starter sanity.config.ts, and adds a sanity/ directory with example schemas.

The full sequence from a clean Next.js 16 repo:

# 1. Provision the project and write starter config
npx sanity@latest init

# 2. Install the Next.js bridge and the image URL helper
npm install next-sanity @sanity/image-url

When sanity init runs, it walks you through a short CLI prompt:

Sign in with email, GitHub, or Google (browser tab opens).
Pick "Create new project" and give it a name.
Pick production as the default dataset.
Choose "Yes" when it asks to add the example schema (you will replace it shortly).
Pick TypeScript and the npm package manager when prompted.

The CLI prints two values at the end: a project ID (an eight-character string) and a dataset name (production). Drop them into .env.local exactly as they are:

# .env.local
NEXT_PUBLIC_SANITY_PROJECT_ID=your_project_id
NEXT_PUBLIC_SANITY_DATASET=production
SANITY_API_READ_TOKEN=optional_for_drafts

The NEXT_PUBLIC_ prefix is required. The Studio runs in the browser and needs to read both values from process.env at build time. The third variable is only needed later if you want the public site to render unpublished drafts for previews.

How do you wire the embedded Studio route at /studio?

Create two files: sanity.config.ts at the project root, and a catch-all route at app/studio/[[...tool]]/page.tsx. The route imports the config and hands it to the NextStudio component, which does the actual rendering.

The config file is where you declare the project ID, dataset, base path, plugins, and your schema list. A minimal version for a blog looks like this:

// sanity.config.ts
import { defineConfig } from 'sanity';
import { structureTool } from 'sanity/structure';
import { visionTool } from '@sanity/vision';
import { schemaTypes } from './sanity/schemaTypes';

export default defineConfig({
  name: 'default',
  title: 'My Blog Studio',
  projectId: process.env.NEXT_PUBLIC_SANITY_PROJECT_ID!,
  dataset: process.env.NEXT_PUBLIC_SANITY_DATASET!,
  basePath: '/studio',
  plugins: [structureTool(), visionTool()],
  schema: { types: schemaTypes },
});

Two things matter here. basePath: '/studio' tells the Studio where it is mounted, so internal links point at /studio/structure/post and not the root. plugins always includes structureTool() (the document list and editor) and, for development, visionTool() (a GROQ query playground).

The route file is short. It imports the config, exports the metadata and viewport that next-sanity already prepared, and renders the Studio:

// app/studio/[[...tool]]/page.tsx
import { NextStudio } from 'next-sanity/studio';
import config from '../../../sanity.config';

export const dynamic = 'force-static';
export { metadata, viewport } from 'next-sanity/studio';

export default function StudioPage() {
  return <NextStudio config={config} />;
}

force-static makes the route itself a static shell. The Studio is a heavy client bundle and there is no benefit to re-rendering the shell on every request. The actual editor work happens client-side once the shell ships.

Once these two files exist, start the dev server with npm run dev and open http://localhost:3000/studio. The Studio loads, asks you to sign in, and then shows the document list. Right now the list is empty because you have not defined any schema types yet.

Source: Sanity Learn: Day one with Sanity Studio

The screenshot above is from the official Sanity learn course, showing the Studio chrome and the document creation menu populated by schema types. Once you add the schemas in the next section, your menu will show Post, Author, and Category in place of those examples.

This three-layer architecture is the part that makes the embedded approach worthwhile. The same browser session talks to two Next.js routes that talk to the same Sanity project, with the editor on the write path and the public pages on the read path:

How do you write a real content schema (post + author + category)?

Create a sanity/schemaTypes/ directory with one file per document type, then export them as an array from sanity/schemaTypes/index.ts. Each file describes the shape of one document using the defineType and defineField helpers from the sanity package.

For a blog you want three documents. A post holds the article. An author holds the person who wrote it. A category groups posts. Posts reference authors and categories, so editors fill in those fields with a dropdown instead of free text.

Start with post.ts:

// sanity/schemaTypes/post.ts
import { defineField, defineType } from 'sanity';

export const post = defineType({
  name: 'post',
  title: 'Post',
  type: 'document',
  fields: [
    defineField({
      name: 'title',
      type: 'string',
      validation: (r) => r.required().max(80),
    }),
    defineField({
      name: 'slug',
      type: 'slug',
      options: { source: 'title', maxLength: 96 },
      validation: (r) => r.required(),
    }),
    defineField({ name: 'author', type: 'reference', to: [{ type: 'author' }] }),
    defineField({
      name: 'category',
      type: 'reference',
      to: [{ type: 'category' }],
    }),
    defineField({
      name: 'mainImage',
      type: 'image',
      options: { hotspot: true },
      fields: [{ name: 'alt', type: 'string', title: 'Alt text' }],
    }),
    defineField({ name: 'publishedAt', type: 'datetime' }),
    defineField({ name: 'body', type: 'blockContent' }),
  ],
});

A few choices worth flagging. validation: r => r.required().max(80) runs in the Studio in real time, so editors see the red warning the moment a title is empty or too long. options: { source: 'title' } on the slug field wires up the "Generate" button, which converts the title to a URL slug. options: { hotspot: true } on the image field lets editors pick a focal point so Sanity can crop responsively without cutting off heads.

author.ts and category.ts are smaller:

// sanity/schemaTypes/author.ts
import { defineField, defineType } from 'sanity';

export const author = defineType({
  name: 'author',
  title: 'Author',
  type: 'document',
  fields: [
    defineField({ name: 'name', type: 'string', validation: (r) => r.required() }),
    defineField({
      name: 'slug',
      type: 'slug',
      options: { source: 'name' },
      validation: (r) => r.required(),
    }),
    defineField({ name: 'avatar', type: 'image', options: { hotspot: true } }),
    defineField({ name: 'bio', type: 'text', rows: 3 }),
  ],
});

// sanity/schemaTypes/category.ts
import { defineField, defineType } from 'sanity';

export const category = defineType({
  name: 'category',
  title: 'Category',
  type: 'document',
  fields: [
    defineField({ name: 'title', type: 'string', validation: (r) => r.required() }),
    defineField({
      name: 'slug',
      type: 'slug',
      options: { source: 'title' },
      validation: (r) => r.required(),
    }),
    defineField({ name: 'description', type: 'text', rows: 2 }),
  ],
});

The blockContent type that the post body uses is the portable text format Sanity ships for rich text. It is a one-line export:

// sanity/schemaTypes/blockContent.ts
import { defineType } from 'sanity';

export const blockContent = defineType({
  name: 'blockContent',
  title: 'Block Content',
  type: 'array',
  of: [{ type: 'block' }, { type: 'image', options: { hotspot: true } }],
});

The index file wires them together:

// sanity/schemaTypes/index.ts
import { post } from './post';
import { author } from './author';
import { category } from './category';
import { blockContent } from './blockContent';

export const schemaTypes = [post, author, category, blockContent];

Reload http://localhost:3000/studio. The Studio picks up the new types and the document list now shows Post, Author, and Category. Create one of each. The reference fields will let you link a post to the author and category you just made.

Source: Sanity Learn: Day one with Sanity Studio

This is what the editor looks like for a real document: the list pane on the left, the document with its declared fields on the right, drafts and publish state at the top. With the schema above, your screen looks the same shape, with your post fields in place of the Name shown here.

How do you query Sanity content from a Server Component?

Create a thin client wrapper at lib/sanity/client.ts, then import it from any Server Component that needs to render content. The client uses GROQ, Sanity's query language, which feels like JSON Path with projections.

The wrapper is short:

// lib/sanity/client.ts
import { createClient } from 'next-sanity';

export const sanityClient = createClient({
  projectId: process.env.NEXT_PUBLIC_SANITY_PROJECT_ID!,
  dataset: process.env.NEXT_PUBLIC_SANITY_DATASET!,
  apiVersion: '2026-06-01',
  useCdn: true,
});

export const allPostsQuery = `*[_type == "post"] | order(publishedAt desc) {
  _id,
  title,
  "slug": slug.current,
  publishedAt,
  "author": author->name,
  "category": category->title
}`;

A few specifics. apiVersion is a calendar date that pins query behavior, so a Sanity-side change does not silently alter your responses. Update it when you adopt a new feature. useCdn: true reads from the public CDN, which is fast and free for published content. Set it to false for draft previews where you want fresh data.

GROQ itself is compact. *[_type == "post"] filters every document by type. The | pipe sorts. The projection block at the end picks fields and rewrites them: "slug": slug.current flattens the slug object to a string, and "author": author->name follows the reference and pulls the author's name in one query.

A Server Component that lists posts is then just:

// app/blog/page.tsx
import { sanityClient, allPostsQuery } from '@/lib/sanity/client';

type PostRow = {
  _id: string;
  title: string;
  slug: string;
  publishedAt: string;
  author: string;
  category: string;
};

export default async function BlogIndexPage() {
  const posts = await sanityClient.fetch<PostRow[]>(allPostsQuery);
  return (
    <ul>
      {posts.map((p) => (
        <li key={p._id}>
          <a href={`/blog/${p.slug}`}>{p.title}</a>
          <span>
            {' '}
            by {p.author} in {p.category}
          </span>
        </li>
      ))}
    </ul>
  );
}

This is a Server Component, so the query runs at request time on Vercel, not in the browser. The response is HTML by the time it reaches the user. For static caching, swap to Cache Components with 'use cache' and a cacheTag keyed off post, and trigger revalidation from a Sanity webhook on publish.

How do you configure CORS so the Studio talks to your project?

Open manage.sanity.io, pick your project, go to API , scroll to CORS origins , and add every origin where the embedded Studio will run. Each entry needs the "Allow credentials" toggle turned on.

The minimum allowlist for a Vercel-hosted Next.js app is three rows:

Origin	When it matters	Allow credentials
`http://localhost:3000`	Local dev	ON
`https://www.your-domain.com`	Production	ON
`https://preview-*.your-domain.vercel.app`	Vercel preview URLs	ON

The reason "Allow credentials" must be ON is that the embedded Studio sends the Sanity editor session cookie on every API call. Without that toggle, the browser strips the cookie before sending the request, Sanity sees an anonymous call, and you get a blank Studio with a console error like CORS policy: No 'Access-Control-Allow-Credentials' header is present on the requested resource. It is the single most common failure when first setting up the embedded Studio.

Restart npm run dev after adding the localhost entry. The dev server picks up the new CORS allowance on the next page load, and the Studio finishes mounting instead of stalling on the login screen.

How do you deploy the embedded Studio to Vercel?

Add the two NEXT_PUBLIC_SANITY_* env vars to your Vercel project, push the branch, and the embedded Studio is reachable at your-domain.com/studio as soon as the deploy goes green. There is no separate Sanity build step.

The full Vercel checklist:

Environment variables. In the Vercel dashboard, go to your project, then Settings , then Environment Variables. Add NEXT_PUBLIC_SANITY_PROJECT_ID and NEXT_PUBLIC_SANITY_DATASET for all three environments (Production, Preview, Development). Add SANITY_API_READ_TOKEN only if you wired the draft preview flow.
CORS for production and preview URLs. Back in manage.sanity.io, make sure both https://www.your-domain.com and https://*-your-team.vercel.app are in the CORS allowlist with credentials on. Preview URLs change per commit, so the wildcard saves you from re-adding them on every branch.
Push. The next push triggers a Vercel build. The build compiles the Studio bundle as part of the Next.js build and ships it as a static route, so cold starts are not part of the editor experience.
Test the editor. Open https://www.your-domain.com/studio, sign in, create a document, and confirm the content shows up on the public route.

You can skip the hosted sanity.studio deployment entirely. That product is useful when you want the editor on a different domain from the marketing site (for example, when the marketing site is on a different stack), but for a single Next.js app, the embedded route is fewer moving parts.

What are the common pitfalls in a Next.js 16 + Sanity setup?

Most first-run problems come from four places: missing env vars at build time, missing CORS entries, the wrong apiVersion, and treating the Studio as a normal Next.js route.

In order of how often I have hit them:

process.env.NEXT_PUBLIC_SANITY_PROJECT_ID is undefined in production. Vercel does not read .env.local. Set the variables in the dashboard with the NEXT_PUBLIC_ prefix exactly, then redeploy. A redeploy is required for env changes to take effect.
CORS blank screen on preview URLs. Vercel preview URLs change per branch. Add https://*-your-team.vercel.app once instead of one entry per branch.
Stale data after publishing. If you have ISR or Cache Components on the read path, publish events do not invalidate them automatically. Wire a Sanity webhook to a Next.js route that calls revalidateTag or updateTag on publish.
Studio is wrapped in your site layout. The catch-all route under app/studio/[[...tool]]/page.tsx inherits any layout above it. If your root layout adds a navbar or padding, the Studio renders inside it. Wrap the Studio route in its own segment with a layout that returns the children as-is, so the editor takes the full viewport.

If you build the site on the same Next.js 16 stack I write about, you have probably already seen related setups in the proxy.ts post about routing middleware and the docs generator post about content-driven pages. The Sanity Studio embed is the read/write half of the same problem those posts cover from the routing and rendering sides.

What did we just build?

A real CMS dashboard at /studio inside a Next.js 16 app, backed by a typed schema for posts, authors, and categories, queried from Server Components, with CORS configured for local and production, deployed on the same Vercel build as the public site. No extra infrastructure, no second domain, no separate auth flow. The whole thing fits in two config files, one route, and a sanity/ directory.

The next step depends on what you ship next. If editors will write drafts you want to preview before publishing, set up the Presentation tool and a draft-mode route on the Next.js side. If you want to render rich text from the body field, install @portabletext/react and write a custom renderer for your design system. If you want full-text search, add searchTool to the plugins list and you get a search bar in the Studio header for free.

For reference, the primary docs I used while writing this are the official Next.js integration guide, the embedding Sanity Studio doc, the Sanity Studio installation requirements, the next-sanity toolkit on GitHub, and the Sanity platform changelog covering the Next.js 16 migration. The Studio screenshots in this post are from the Day One with Sanity Studio learn course on the Sanity site.

Keep Reading

How to Version REST APIs in Spring Framework 7 (Spring Boot 4)

Rabinarayan Patra — Tue, 02 Jun 2026 18:30:00 +0000

For years, versioning a Spring REST API meant picking your own poison. Custom interceptors, duplicate controllers, or a pile of headers= conditions on every mapping. Spring Framework 7, the core of Spring Boot 4, ends that. Versioning is now a first-class feature baked into request mapping.

I rebuilt a multi-version API on Spring Boot 4 last month and deleted about 300 lines of routing glue in the process. This guide is the playbook I wish I'd had: every strategy, real controller code, a curl trace per approach, and the deprecation headers that tell clients when to move on.

What changed for API versioning in Spring Framework 7?

Spring Framework 7 added a version attribute to @RequestMapping and every shortcut variant, so one path can fan out to multiple handlers by version. Before this, request mapping had no concept of a version at all. You bolted versioning on from the outside with interceptors or separate controller classes per release.

The new model has three moving parts. A resolver pulls the version out of the request. A parser turns that raw string into a comparable semantic version. A strategy matches it against the version declared on each mapping and picks the closest handler. All three are configurable, and the defaults cover the common cases.

Here's the smallest possible example. Same path, two versions, two methods:

@RestController
@RequestMapping("/accounts")
public class AccountController {

    @GetMapping(path = "/{id}", version = "1.0")
    public AccountV1 getAccountV1(@PathVariable Long id) {
        return accountService.findV1(id);
    }

    @GetMapping(path = "/{id}", version = "2.0")
    public AccountV2 getAccountV2(@PathVariable Long id) {
        return accountService.findV2(id);
    }
}

A request for version 1.0 hits the first method. A request for 2.0 hits the second. No if checks, no manual parsing, no shared dispatcher method. The version is part of the mapping, exactly like the path and the HTTP method.

How do you turn on API versioning in Spring Boot 4?

You turn on versioning by implementing WebMvcConfigurer and overriding configureApiVersioning, which hands you an ApiVersionConfigurer. Nothing routes by version until you declare which resolver to use. The version attribute on a mapping is inert without a configured strategy.

@Configuration
public class ApiVersioningConfig implements WebMvcConfigurer {

    @Override
    public void configureApiVersioning(ApiVersionConfigurer configurer) {
        configurer.useRequestHeader("X-API-Version")
                  .addSupportedVersions("1.0", "2.0");
    }
}

That's the entire wiring for header-based versioning. useRequestHeader names the header to read. addSupportedVersions declares the versions you accept, which lets Spring reject anything unknown with a clean 400 instead of a confusing 404.

If you'd rather stay in properties, Spring Boot 4 exposes the same switch:

spring.mvc.apiversion.use.header=X-API-Version

By default a version is required. A request with no version triggers MissingApiVersionException and a 400 response. An unsupported version triggers InvalidApiVersionException, also a 400. You can relax both, and I'll cover that under pitfalls, because the default trips up first-time users.

How does the version attribute route requests?

The version attribute routes a request by comparing the resolved request version against the version declared on each candidate mapping, then choosing the best match. Spring parses both sides with SemanticApiVersionParser, which reads major.minor.patch and fills missing parts with zero. So "1" becomes 1.0.0 and "1.2" becomes 1.2.0.

Matching is not a naive string equality. If a request asks for 1.5 and your handlers declare 1.0 and 2.0, the request resolves to the highest version less than or equal to 1.5, which is 1.0. That single rule is what makes baseline versioning work, and it's why you don't need a handler for every point release.

The flow is the same no matter which strategy you choose. Only the first box, the resolver, changes. Pick where the version lives in the request and the rest of the pipeline stays identical.

Which versioning strategy should you pick?

Spring Framework 7 ships four resolver strategies, and you choose one with a single method on ApiVersionConfigurer. Each reads the version from a different place in the request. The handler code never changes. Only the config line and the way clients call you differ.

Request header

Header versioning keeps the URL clean and puts the version in a custom header. This is my default for service-to-service APIs.

configurer.useRequestHeader("X-API-Version")
          .addSupportedVersions("1.0", "2.0");

curl -H "X-API-Version: 2.0" http://localhost:8080/accounts/42

Path segment

Path-segment versioning puts the version directly in the URL, which makes it visible, bookmarkable, and easy to route at a proxy. You declare which segment holds the version by index and add a URI variable for it in the mapping.

configurer.usePathSegment(1)
          .addSupportedVersions("1.0", "2.0");

@GetMapping(path = "/api/{version}/accounts/{id}", version = "2.0")
public AccountV2 getAccount(@PathVariable Long id) {
    return accountService.findV2(id);
}

curl http://localhost:8080/api/2.0/accounts/42

Segment index is zero-based against the path. In /api/2.0/accounts/42 the segments are api, 2.0, accounts, 42, so the version sits at index 1.

Query parameter

Query-parameter versioning reads the version from the query string. It's trivial to test in a browser and trivial to forget in a cache key, so weigh that tradeoff.

configurer.useQueryParam("version")
          .addSupportedVersions("1.0", "2.0");

curl "http://localhost:8080/accounts/42?version=2.0"

Media type

Media-type versioning reads a parameter off the Accept header, which is the most REST-purist option and the hardest for casual clients to send.

configurer.useMediaTypeParameter(MediaType.APPLICATION_JSON, "version")
          .addSupportedVersions("1.0", "2.0");

curl -H "Accept: application/json;version=2.0" http://localhost:8080/accounts/42

My rule of thumb: header for internal APIs, path segment for public APIs where humans read the URLs, and skip query and media type unless you have a specific reason. The worst choice is no choice, where different endpoints use different strategies and clients can't predict which one applies.

What's the difference between fixed and baseline versions?

A fixed version matches one exact version, while a baseline version matches that version and everything above it until a higher handler takes over. You write a fixed version as "1.2" and a baseline version with a trailing plus, "1.2+". The difference is how many releases a single handler is responsible for.

Picture an endpoint that hasn't changed since 1.0 and another that got a new shape in 2.0:

@RestController
@RequestMapping("/accounts")
public class AccountController {

    @GetMapping(path = "/{id}", version = "1.0+")
    public AccountV1 getAccount(@PathVariable Long id) {
        return accountService.findV1(id);
    }

    @PostMapping(version = "2.0+")
    public AccountV2 createAccount(@RequestBody CreateAccount body) {
        return accountService.createV2(body);
    }
}

The GET handler answers 1.0, 1.5, 1.9, and anything up to the next declared version. The POST handler owns 2.0 and up. You only write a new method when the contract actually changes, not on every version bump. That's the whole point of baseline matching, and it's why a real API with ten releases might have three or four handlers per route instead of ten.

Fixed versions still matter. Use them when a single release introduced a breaking change you want pinned to one exact handler, so a typo in a client's version string fails loudly instead of silently falling through to an older shape.

How do you deprecate an API version with Sunset headers?

You deprecate a version by registering a StandardApiVersionDeprecationHandler and configuring a deprecation date, a sunset date, and a migration link per version. Spring then attaches three response headers to every matching request: Deprecation from RFC 9745, Sunset from RFC 8594, and a Link pointing at your migration docs. Clients that watch for these headers learn a version is going away without reading your changelog.

@Configuration
public class ApiVersioningConfig implements WebMvcConfigurer {

    @Override
    public void configureApiVersioning(ApiVersionConfigurer configurer) {
        StandardApiVersionDeprecationHandler handler =
                new StandardApiVersionDeprecationHandler();

        handler.configureVersion("1.0")
               .setDeprecationDate(ZonedDateTime.parse("2026-06-01T00:00:00Z"))
               .setSunsetDate(ZonedDateTime.parse("2026-12-01T00:00:00Z"))
               .setSunsetLink(URI.create("https://api.example.com/docs/migrate-to-2.0"));

        configurer.useRequestHeader("X-API-Version")
                  .addSupportedVersions("1.0", "2.0")
                  .setDeprecationHandler(handler);
    }
}

Now a call to the deprecated version carries the warning in its response:

curl -i -H "X-API-Version: 1.0" http://localhost:8080/accounts/42

HTTP/1.1 200 OK
Deprecation: Mon, 01 Jun 2026 00:00:00 GMT
Sunset: Tue, 01 Dec 2026 00:00:00 GMT
Link: <https://api.example.com/docs/migrate-to-2.0>; rel="sunset"
Content-Type: application/json

The version still works. Deprecation is a signal, not a shutdown. When the sunset date passes and you're confident traffic has moved, you drop the 1.0 handler and remove "1.0" from the supported versions. Clients that ignored the headers get a clean 400, and you have the access logs to prove you warned them.

How was this done before Spring 7?

Before Spring 7 you versioned by hand, and every approach had a sharp edge. The most common pattern was duplicate controllers, one class per version, wired to different base paths:

@RestController
@RequestMapping("/v1/accounts")
public class AccountControllerV1 { /* ... */ }

@RestController
@RequestMapping("/v2/accounts")
public class AccountControllerV2 { /* ... */ }

That works until you have twenty endpoints across four versions and a bug fix has to land in three of them. The other common hack abused the headers condition on a mapping:

@GetMapping(path = "/accounts/{id}", headers = "X-API-Version=1")
public AccountV1 getV1(@PathVariable Long id) { /* ... */ }

String equality only. No 1.0 versus 1 normalization, no baseline ranges, no 1.5 falling back to 1.0. You hand-rolled every comparison. Teams that wanted real semantics wrote a custom HandlerInterceptor to parse and validate versions, then threaded the result through ThreadLocal or request attributes. It was a lot of code to maintain, and it lived nowhere near the mappings it controlled.

The built-in approach wins on every axis I care about. Versioning lives on the mapping where you can see it, comparison is semantic, baseline matching cuts handler count, and deprecation headers come free. The 300 lines I deleted were exactly this kind of glue.

What pitfalls should you watch for?

The first pitfall is the required-version default, which surprises everyone. A request with no version returns a 400, not your newest handler. If you want missing versions to fall back instead of failing, set a default and mark versions optional:

configurer.useRequestHeader("X-API-Version")
          .addSupportedVersions("1.0", "2.0")
          .setVersionRequired(false)
          .setDefaultVersion("2.0");

With setVersionRequired(false) and no default, Spring falls back to the most recent supported version, which may not be what you want during a migration. Always pair optional versions with an explicit setDefaultVersion so the fallback is a decision, not an accident.

The second pitfall is supported-version detection. By default Spring initializes the supported set from the versions it finds on your controller mappings, so a typo like version = "20" silently becomes a supported version. If you want a locked allowlist, call detectSupportedVersions(false) and declare every version with addSupportedVersions yourself. I do this on public APIs so nothing ships a version by accident.

The third pitfall is OpenAPI tooling. As of mid-2026, springdoc support for the new version attribute is still catching up, so two handlers on the same path can confuse schema generation. Until your springdoc version understands the version dimension, group your docs per version or document the version header manually in your OpenAPI config. Test your generated spec before you assume it rendered both versions.

The last one is strategy drift. Once you pick a resolver, every endpoint must use it. A header-versioned API with one path-versioned endpoint will route inconsistently and break client SDKs that assume one scheme. Decide the strategy at the start of the project and enforce it in review.

Is built-in versioning worth migrating to?

Yes, and it changes how you think about API evolution, not just how you wire it. When adding a version is one attribute and one method, you stop dreading breaking changes and start shipping them cleanly, because the cost of carrying an old contract next to a new one dropped to almost nothing. That's the real shift in Spring Framework 7. The mechanics are simple. The freedom they buy is the point.

Start with header versioning and a required version on a single endpoint. Add a 2.0 handler with a baseline range. Wire a deprecation handler with a sunset date six months out. Once that loop feels natural, you'll version everything this way and wonder how you tolerated the interceptor era.

For the authoritative details, read the official Spring blog announcement on API versioning and the Spring Framework reference on MVC API versioning. For the header semantics, see RFC 9745 (Deprecation) and RFC 8594 (Sunset).

Keep Reading

How to Configure CORS in Spring Boot. Get cross-origin headers right before you expose a versioned API.
How to Test Spring Boot with Testcontainers. Write integration tests that exercise each API version against a real database.
Spring Security's Component Revolution. Secure the versioned endpoints you just built.
Modern Java with Spring Boot. The language features that make Spring Boot 4 controllers cleaner.

How to Set Up an SSH Tunnel for Local Database Access

Rabinarayan Patra — Thu, 28 May 2026 18:30:00 +0000

The single fastest way to wake up to a ransom note is to expose your Postgres port directly to the public internet. The second fastest is to think you can secure it with a strong password and call it a day.

I have run point on database access for production systems at three different companies. Every single one of them had at least one engineer at some point ask if we could "just open 5432 to my IP" so they could pull a quick report from DBeaver. The answer is always no. The right answer is an SSH tunnel, and once you have done it twice, it takes about 15 seconds to set up.

This post is the practical guide I wish I had given that engineer the first time. We will cover the command, the GUI client setup for the four databases I touch most often, the autossh recipe that keeps the tunnel alive through laptop sleeps and network changes, and the small set of mistakes that bite people in production. If you want the deeper context on why exposing database ports is bad even with strong auth, I covered that in my zero-trust microservices post, and the connection pooling tradeoffs once you are inside the tunnel show up in my pgbouncer survival guide.

What is an SSH tunnel and why use it for database access?

An SSH tunnel for database access forwards a local TCP port on your laptop through an authenticated SSH session to a remote host, which then opens a connection to the actual database. Your database client connects to localhost and never knows anything else exists. All traffic rides inside the encrypted SSH channel.

The shape of it looks like this.

This pattern wins on five things at once.

No exposed database port. The database listens only on its private network. The bastion is the only thing on the public internet, and it only speaks SSH.

No firewall holes per developer. Every engineer goes through the same bastion. You add or remove access by adding or removing SSH keys, not by editing security group rules.

Audit trail. Every connection logs through SSH and through the bastion's auth.log. You know who connected, from where, when.

Works with every client. psql, DBeaver, TablePlus, DataGrip, mysql, redis-cli, mongosh. They all just see localhost. No driver-level config needed.

Encrypted in transit by default. Even if your database speaks plaintext on the wire (looking at you, Redis), the tunnel carries it under SSH.

The one thing it does not give you is high availability. The tunnel is a long-lived TCP connection between exactly two hosts. If your bastion goes down, your tunnel goes with it. That is fine for ad-hoc developer access. It is not fine for application traffic. Application traffic belongs on a private network or a managed bastion service like AWS Session Manager.

How do you set up a local port forward to a remote Postgres?

The full command is one line.

ssh -L 5433:dbhost.internal:5432 ec2-user@bastion.example.com

Read it left to right.

-L 5433:dbhost.internal:5432 says forward local port 5433 on this laptop, through the SSH connection, to dbhost.internal:5432 resolved from the bastion's perspective.
ec2-user@bastion.example.com is the SSH connection itself.

While that command is running, anything on your laptop that connects to localhost:5433 ends up talking to the Postgres on dbhost.internal:5432. Close the terminal or hit Ctrl+C and the tunnel dies.

I deliberately use 5433 on the local side instead of 5432. If you happen to have Postgres running locally for development, you do not want to clobber it. Pick a high port that does not collide.

To test the tunnel works without firing up a GUI, use psql from another terminal.

psql -h localhost -p 5433 -U app_user -d production

That -h localhost is the key. Without it, psql tries to connect via Unix socket and skips the tunnel entirely. I have lost 20 minutes to this twice.

Running the tunnel in the background

If you do not want a terminal sitting open, add -f -N and the command returns immediately while the tunnel keeps running.

ssh -f -N -L 5433:dbhost.internal:5432 ec2-user@bastion.example.com

-N means do not execute a remote command (we only want the forward).
-f means fork into the background after authentication.

To kill it later, find and stop the process.

pgrep -af "ssh.*5433:dbhost.internal"
kill <pid>

A tidier setup with `~/.ssh/config`

Typing that command every time gets old. Stash the whole thing in your SSH config.

# ~/.ssh/config
Host pg-prod
    HostName bastion.example.com
    User ec2-user
    IdentityFile ~/.ssh/keys/prod-bastion.pem
    LocalForward 5433 dbhost.internal:5432
    ServerAliveInterval 30
    ServerAliveCountMax 3
    ExitOnForwardFailure yes

Now the command is just ssh pg-prod, and you get a few useful behaviors for free.

ServerAliveInterval 30 sends a keepalive every 30 seconds so the tunnel does not die when your home router decides to drop idle connections.
ExitOnForwardFailure yes makes ssh fail fast if the forward cannot bind, instead of leaving you with a dead tunnel and no error.

For the background form, ssh -f -N pg-prod still works. The config entry is purely additive.

How do you connect from your GUI client through the tunnel?

With the tunnel running, every GUI client connects to localhost on the forwarded port. The only field that matters is the host. Everything else (username, password, database name) is the same as you would use against the real database.

In DBeaver, create a new Postgres connection and fill in:

Host: localhost
Port: 5433
Database: production
Username: app_user
Password: <your db password>

Hit Test Connection. If it works, you are good.

In TablePlus, same idea. Host is localhost, port is 5433.

In DataGrip, same. The driver does not know the tunnel exists, which is exactly the point.

DBeaver and DataGrip both have a built-in SSH tunnel option in their connection dialog. That works too. The advantage of using ssh on the command line instead is that you can share one tunnel across psql, DBeaver, a script, and a notebook at the same time. The advantage of the GUI option is that it dies cleanly when you close the client.

I default to the command line approach because I almost always have multiple things hitting the same database. Pick what fits your workflow.

How do you do the same for MySQL, Redis, and MongoDB?

The flag is identical. Only the port changes.

# MySQL
ssh -L 3307:dbhost.internal:3306 user@bastion

# Redis
ssh -L 6380:cache.internal:6379 user@bastion

# MongoDB
ssh -L 27018:mongohost.internal:27017 user@bastion

Then connect each client to localhost on the forwarded port.

mysql -h 127.0.0.1 -P 3307 -u app_user -p
redis-cli -h 127.0.0.1 -p 6380
mongosh "mongodb://app_user:secret@127.0.0.1:27018/production"

A few client-specific notes that catch people.

MySQL needs 127.0.0.1, not localhost. The mysql client tries to connect via Unix socket when you say localhost, just like psql does. Use the IP literal and you skip that.

Redis tunnels work great for debugging, badly for sustained throughput. Every command round-trips through the SSH session. Latency goes from 0.2 ms to 8-30 ms depending on your link. Fine for redis-cli MONITOR or one-off lookups. Wrong tool for ETL.

Mongo replica sets need extra care. A standalone mongod tunnels fine. A replica set will hand you back the internal hostnames of the other replicas during connection negotiation, and your client will then try to connect to those names directly. Either tunnel each replica on its own port and add them to your connection string, or set directConnection=true in the URI to disable replica discovery.

How do you keep the tunnel alive with autossh and systemd?

ssh -f -N works until your laptop goes to sleep, your wifi switches, or the bastion restarts. Then the tunnel dies silently and your next connection just hangs. The fix is autossh, which is a tiny wrapper that monitors the SSH process and restarts it when it drops.

Install it.

# macOS
brew install autossh

# Ubuntu / Debian
sudo apt install autossh

# Fedora / Rocky
sudo dnf install autossh

Run it the same way you ran ssh, with one extra port for autossh's own health check.

AUTOSSH_GATETIME=0 \
autossh -M 0 -f -N \
  -o "ServerAliveInterval 30" \
  -o "ServerAliveCountMax 3" \
  -o "ExitOnForwardFailure yes" \
  -L 5433:dbhost.internal:5432 \
  ec2-user@bastion.example.com

A few details that matter.

AUTOSSH_GATETIME=0 makes autossh restart immediately even if the first connection failed. Without it, autossh waits 30 seconds before retrying, which is annoying when you mis-typed the host.
-M 0 disables autossh's old monitoring port mechanism. We use the ServerAlive* SSH options instead, which work better through NATs and modern firewalls.

That command stays up through sleep, wake, and network changes. But it does not survive a reboot. For that, wrap it in a systemd user service.

The systemd user service

Create ~/.config/systemd/user/pg-tunnel.service.

[Unit]
Description=Autossh tunnel to production Postgres
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
Environment=AUTOSSH_GATETIME=0
ExecStart=/usr/bin/autossh -M 0 -N \
  -o "ServerAliveInterval 30" \
  -o "ServerAliveCountMax 3" \
  -o "ExitOnForwardFailure yes" \
  -o "ConnectTimeout 10" \
  -i /home/rabi/.ssh/keys/prod-bastion.pem \
  -L 5433:dbhost.internal:5432 \
  ec2-user@bastion.example.com
Restart=always
RestartSec=10

[Install]
WantedBy=default.target

Notice the ExecStart does not use -f here. Systemd wants the process in the foreground so it can supervise it. The Restart=always line takes over from the -f background behavior.

Enable and start.

systemctl --user daemon-reload
systemctl --user enable --now pg-tunnel.service
systemctl --user status pg-tunnel.service

That last command should show active (running). If you want the service to start at boot (not just at login), enable user lingering once.

sudo loginctl enable-linger $USER

Logs are in journalctl.

journalctl --user -u pg-tunnel.service -f

On macOS, the same job goes into a launchd plist at ~/Library/LaunchAgents/com.rabi.pg-tunnel.plist. The shape is similar enough that I will skip the full XML, but the key entries are KeepAlive set to true and a ProgramArguments array that mirrors the autossh command above.

What are the common SSH tunnel mistakes to avoid?

I have made every one of these. So has everyone I have onboarded.

Binding the forward to 0.0.0.0 instead of 127.0.0.1. The default -L 5433:dbhost:5432 binds to localhost only. If you write -L *:5433:dbhost:5432, you have just opened your laptop's port 5433 to anyone on the same wifi network as you. They can now talk to your production Postgres. Do not do this. The local bind defaults to localhost for a reason.

Hardcoding production credentials in ~/.ssh/config. SSH config has no concept of secrets management. If you check your config into a dotfiles repo, that key path goes with it. Keep production keys outside the config-tracked area and reference them by absolute path from a directory that is gitignored.

Forgetting that ServerAliveInterval is client-side only. This tells your laptop to send keepalives. The bastion can still close the connection on its own idle timeout. If your bastion is AWS Systems Manager based or sits behind a corporate load balancer with a short idle, you also need to set keepalives at the server level (ClientAliveInterval in sshd_config). Otherwise your tunnel drops every five minutes and you do not know why.

Trusting the tunnel to give you encryption end-to-end. SSH encrypts the laptop-to-bastion segment. The bastion-to-database segment is in cleartext on your private network. For most production setups, that is fine because the private network is trusted. For sensitive workloads with stricter compliance requirements (PCI, HIPAA), insist on TLS on the database side too, even inside the VPC.

Tunneling through your jump host as root. The bastion is a public-facing box. The account that holds your tunnel should not also be the one with sudo rights. Use a dedicated low-privilege user for tunneling. Restrict it to command="false",no-shell in authorized_keys if you want to be paranoid, with a PermitOpen directive that limits which host:port combos this key can forward to.

The hardened authorized_keys line looks like this.

command="echo 'no shell',no-pty,no-agent-forwarding,no-X11-forwarding,permitopen="dbhost.internal:5432" ssh-ed25519 AAAA... rabi@laptop

That key can open exactly one forward, to exactly one host:port, and cannot execute a shell. If the key leaks, the attacker gets a tunnel to one database, not a shell on your bastion.

Letting the tunnel persist across job changes. This one is process, not technical. When an engineer leaves the team, their SSH keys come out of every bastion's authorized_keys. The keys are in your secrets manager and config-managed. Right? Right.

Using the same bastion for staging and production. I have seen this break twice. A misconfigured LocalForward ends up pointing your TablePlus at production while you think you are on staging. Use separate bastions, separate config entries with distinct host names like pg-prod and pg-stage, and color-code the connections in your client so you cannot confuse them visually.

What does the whole setup look like in 30 seconds?

For the reader who skipped to the end, here is the compressed version.

# One-off
ssh -f -N -L 5433:dbhost.internal:5432 user@bastion
psql -h localhost -p 5433 -U app_user -d production

# Persistent, survives sleep and network changes
brew install autossh
AUTOSSH_GATETIME=0 autossh -M 0 -f -N \
  -o "ServerAliveInterval 30" \
  -L 5433:dbhost.internal:5432 user@bastion

# Persistent, survives reboot (Linux)
# Drop the autossh command into ~/.config/systemd/user/pg-tunnel.service
# and run: systemctl --user enable --now pg-tunnel.service

That is genuinely all you need for 95% of the database access situations a developer hits.

The whole reason this pattern works is that SSH is older than most of the protocols we layer on top of it, and the port-forwarding feature has been battle-tested for three decades. Use it. Stop opening database ports to the internet. Your future self will thank you the next time a Shodan-driven exploit campaign sweeps the internet looking for misconfigured Postgres instances, which is approximately every Tuesday.

For more on the protocol, see the OpenSSH manual page for ssh(1), the autossh project page, and RFC 4254 for the SSH connection protocol spec that defines port forwarding.

Keep Reading

Postgres Connection Pool: A pgbouncer Survival Guide: once you can reach the database, the next question is how many connections you can hold open without melting it.
Zero-Trust Microservices with Spring Security: the bigger frame for why exposing internal ports is the wrong default, even inside a private network.

Spring AI 2.0 MCP Annotations: From Tool to Production

Rabinarayan Patra — Tue, 26 May 2026 18:30:00 +0000

Spring AI 2.0.0-M6 dropped on May 8, 2026. Buried in the release notes was the thing I had been waiting for since I first wired an MCP server in Java six months ago: native annotations. @McpTool, @McpResource, @McpPrompt, @McpComplete. All in core. All auto-registered.

If you've written an MCP server with the older Spring AI ToolCallback API, you remember the ritual. Build descriptors, register callbacks, wire up the transport manually, handle JSON schema by hand. The annotation API replaces all of it with a single annotation on a method. Spring AI generates the schema. Auto-configuration handles registration. You write the business logic.

This tutorial walks the full path: building a production MCP server, exposing tools and resources, handling async work with progress reporting, picking a transport, registering with Claude Code, and the gotchas I've hit that nobody mentions on the docs.

What changed in Spring AI 2.0 MCP annotations?

Spring AI 2.0 collapses MCP server and client wiring into a small set of annotations that Spring Boot auto-configuration picks up at startup. The annotated beans become the MCP surface for your Spring Boot app.

The core server annotations are:

@McpTool marks a method as an MCP tool. Spring AI builds the JSON schema from your method parameters.
@McpResource exposes a resource via a URI template.
@McpPrompt exposes a prompt template that clients can fetch.
@McpComplete provides auto-completion for prompt or resource arguments.

The auto-configuration also injects special context parameters like McpSyncRequestContext and McpAsyncRequestContext, which give your method access to logging, progress reporting, sampling, and elicitation without polluting the JSON schema.

For a Spring shop, this is the kind of API change that flips a project's complexity. Before, every team building an MCP server wrote the same plumbing. Now the plumbing is gone.

How do you build an MCP server with @McpTool?

Start with a Spring Boot 3.5+ project on Java 21 or higher. Add the MCP server starter to your pom.xml. There are three flavors: stdio/SSE default, WebMVC, and WebFlux. For production HTTP transport, pick WebMVC or WebFlux based on whether you want blocking or reactive code.

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
    <version>2.0.0-M6</version>
</dependency>

Spring AI 2.0 milestones live in the Spring milestone repository, so add it if you haven't:

<repositories>
    <repository>
        <id>spring-milestones</id>
        <name>Spring Milestones</name>
        <url>https://repo.spring.io/milestone</url>
    </repository>
</repositories>

Now write a tool. The example everyone reaches for first is a calculator, but let's do something a real MCP client would actually want: fetching a user record from your database.

import org.springframework.ai.mcp.server.annotation.McpTool;
import org.springframework.ai.mcp.server.annotation.McpToolParam;
import org.springframework.stereotype.Component;

@Component
public class UserTools {

    private final UserRepository users;

    public UserTools(UserRepository users) {
        this.users = users;
    }

    @McpTool(
        name = "get_user",
        description = "Fetch a user record by ID. Returns name, email, and signup date."
    )
    public UserDto getUser(
        @McpToolParam(description = "Numeric user ID", required = true) long userId
    ) {
        return users.findById(userId)
            .map(UserDto::from)
            .orElseThrow(() -> new IllegalArgumentException("User not found: " + userId));
    }
}

That's the whole tool. Spring AI does a few things automatically when it scans this bean:

It builds a JSON schema for the userId parameter using the @McpToolParam description and the Java type. The MCP client sees the schema and shows it as a typed input.

It registers the method with the MCP server runtime under the name get_user. The MCP tools/list request returns it. The tools/call request invokes it.

It serializes the return type using Jackson. UserDto becomes a JSON object in the tool result.

You can also use Map<String, Object> if you want loose typing, or a record class if you want strict typing with deserialization on the client side. Records are my default. The serialization is predictable, the schema is implicit, and the code is less than a Lombok annotation pile would be.

How do you handle progress and async work?

The most common reason a tool feels broken in production is that it does real work without telling the client. The client sits there. The user sits there. Eventually something times out. Spring AI 2.0 fixes this with a request context that exposes a progress channel.

import org.springframework.ai.mcp.server.annotation.McpTool;
import org.springframework.ai.mcp.server.context.McpSyncRequestContext;
import org.springframework.stereotype.Component;

@Component
public class ReportTools {

    private final ReportService reports;

    public ReportTools(ReportService reports) {
        this.reports = reports;
    }

    @McpTool(
        name = "generate_quarterly_report",
        description = "Generate the quarterly revenue report. Takes a few seconds."
    )
    public ReportResult generateReport(
        McpSyncRequestContext ctx,
        @McpToolParam(description = "Quarter, e.g. 2026-Q1", required = true) String quarter
    ) {
        ctx.logging().info("Loading transactions for " + quarter);
        ctx.progress().report(0.1, "Loading transactions");

        var transactions = reports.loadTransactions(quarter);
        ctx.progress().report(0.5, "Aggregating");

        var aggregated = reports.aggregate(transactions);
        ctx.progress().report(0.9, "Rendering");

        return reports.render(aggregated);
    }
}

McpSyncRequestContext does not appear in the JSON schema. Spring AI knows it's a framework parameter and excludes it. The user-facing parameters stay clean. Inside the method you get logging(), progress(), sampling(), and elicitation() channels, all wired to the MCP client transport.

For reactive code, use McpAsyncRequestContext and return a Mono or Flux. The progress channel returns Reactor types so you can compose progress reporting into a reactive chain.

@McpTool(name = "async_report", description = "Generate report asynchronously.")
public Mono<ReportResult> asyncReport(
    McpAsyncRequestContext ctx,
    @McpToolParam(description = "Quarter") String quarter
) {
    return reports.loadAsync(quarter)
        .doOnNext(_ -> ctx.progress().report(0.5, "Aggregated").subscribe())
        .flatMap(reports::renderAsync);
}

One thing to flag: the progress channel is not the same thing as streaming results. Progress is metadata. The result is still a single return value. If you want token-by-token streaming, you want sampling, not tools.

How do you expose prompts and resources?

Tools are the most-used MCP primitive, but prompts and resources are what turn a tool collection into a workspace. Prompts let the client request a prefilled prompt template. Resources let the client browse data your server exposes by URI.

A prompt looks like this:

@Component
public class IncidentPrompts {

    @McpPrompt(
        name = "incident_summary",
        description = "Generate an incident summary from a Jira ticket ID."
    )
    public String incidentSummary(
        @McpToolParam(description = "Jira ticket ID, e.g. INC-1234") String ticketId
    ) {
        return """
            Summarize the incident in ticket %s for an executive audience.
            Include: timeline, root cause, customer impact, and remediation.
            """.formatted(ticketId);
    }
}

When the client asks for the incident_summary prompt with INC-1234, the server returns the rendered string. The client passes it to its model.

Resources are different. They expose data the server holds, keyed by URI:

@Component
public class CustomerResources {

    private final CustomerRepository customers;

    public CustomerResources(CustomerRepository customers) {
        this.customers = customers;
    }

    @McpResource(
        uri = "customer://{customerId}/profile",
        description = "Customer profile data including billing address and tier."
    )
    public CustomerProfile profile(String customerId) {
        return customers.profileFor(customerId);
    }
}

The client can list resources, pick one, and read it. The URI template is matched on the path variable. Spring AI extracts the customerId and passes it to the method.

The combination of tools, prompts, and resources is what makes MCP feel like an actual application surface rather than a function bag. Tools do work. Prompts give the client wording. Resources expose state.

How do you choose between transports (stdio, SSE, Streamable HTTP)?

Spring AI supports four transports, and the choice matters more than the docs make it sound.

stdio is for local single-process tools. Claude Code spawns your server as a child process and talks to it over stdin and stdout. Fine for personal tooling. Bad for anything multi-user, multi-tenant, or networked.

SSE was the original HTTP transport for MCP. It's being phased out. Spring AI still ships it for backward compatibility, but new servers should not start there.

Streamable HTTP is the current MCP HTTP transport. Stateful, supports bidirectional notifications, works behind reverse proxies, fits production environments. Use this for any server that isn't strictly local.

Stateless Streamable HTTP is the new variant designed for serverless and horizontally scaled deployments. No session affinity required. The tradeoff is that any context that would have lived in the server session has to come back through the request from the client. If you're deploying to Vercel, Cloud Run, or any autoscaled platform, this is your transport.

For Streamable HTTP with WebMVC, the auto-config wires it up at /mcp by default. You can change the path:

spring:
  ai:
    mcp:
      server:
        transport: streamable-http
        path: /api/mcp
        name: my-spring-server
        version: 1.0.0

The name and version show up in the MCP initialize response. Set them to something recognizable. Default Spring AI names look generic in client UIs.

How do you register and test the server with Claude Code?

Once your Spring Boot app runs and exposes Streamable HTTP at /mcp, register it with Claude Code. The config lives in ~/.config/claude/mcp.json on macOS and Linux, or via the claude mcp CLI.

{
  "mcpServers": {
    "my-spring-server": {
      "type": "streamable-http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

Restart Claude Code. Run /mcp inside a session. You should see your tools, prompts, and resources listed. Try calling one. If the call returns and the result shows up in your transcript, the loop is alive.

For local stdio testing, swap the JSON to type stdio and point command at your packaged jar:

{
  "mcpServers": {
    "my-spring-server": {
      "type": "stdio",
      "command": "java",
      "args": ["-jar", "/path/to/server.jar"]
    }
  }
}

Claude Code will spawn the JVM, talk over stdin and stdout, and shut it down when the session ends. The startup cost is real, somewhere between 2 and 5 seconds depending on your dependencies. For HTTP transport, Spring Boot stays running and connections are cheap.

What are the production-readiness gotchas?

The annotation API hides the complexity. That's a feature for most cases, but it also means a few production concerns aren't obvious until they bite.

Error handling. If your @McpTool method throws, Spring AI wraps the exception and returns an MCP error to the client. Good. But the default error mapping returns the exception message verbatim, which can leak internal details. Customize the error handling with a McpExceptionHandler bean if you're exposing the server to untrusted clients.

Schema generation. Records and POJOs work. Generic collections work. Nested polymorphic types are where the generator gets cranky. If your tool returns a List<Animal> where Animal is an interface, expect the schema to be vague. Prefer concrete types for tool return values. Save the polymorphism for internal layers.

Auth. Spring AI does not ship MCP-specific auth. You wire it through normal Spring Security. For Streamable HTTP, add a security filter chain matching /mcp and validate bearer tokens or API keys there. The Stateless Streamable HTTP transport makes this easier because there's no session to protect, only requests.

Long-running tools. MCP clients have timeouts. Claude Code's default is generous but not infinite. If your tool runs longer than 30 seconds, use the progress channel aggressively, and consider returning a job handle and exposing a second tool to poll status. Trying to hold open a 5-minute synchronous tool call will end in tears.

Scaling. Streamable HTTP is stateful per session. Sticky sessions or a shared session store are needed if you scale horizontally. If you want stateless scaling, use the Stateless Streamable HTTP transport and design your tools to be self-contained on each request.

Tool naming. MCP tool names show up in the client UI. Pick verbs. get_user reads better than userQuery. Consistency matters more than cleverness.

Conclusion

The Spring AI 2.0 MCP annotation API is the kind of upgrade you only notice fully when you look back at the old way. The boilerplate is gone. The schema generation is automatic. The transports are real. The progress and async story is sane.

The part I want more Spring teams to internalize: MCP is no longer an experiment. Every major coding agent speaks it. Every Spring service in your fleet is a potential MCP surface. The cost of exposing your internal APIs to an agent has dropped to almost nothing. Whether that's a good idea is a different conversation, but the technical barrier is now low enough that you should decide on purpose, not by default.

For more on Spring AI MCP, see the Spring AI MCP annotations docs, the Spring AI 2.0.0-M6 release post, and the official MCP spec.

Keep Reading

Claude Skills vs MCP vs Projects. When to reach for an MCP server vs a skill or a project.
Claude Code Routines for CI Automation. Wiring agents into CI once your MCP server is live.
Modern Java + Spring Boot. The Spring Boot 3.x baseline you need before Spring AI 2.0.

Why MCP 2026-07-28 Spec Drops Sessions and Goes Stateless

Rabinarayan Patra — Sun, 24 May 2026 18:30:00 +0000

The MCP team locked the 2026-07-28 spec release candidate on May 21. It is the largest revision since launch and yes, it breaks things. If you are running an MCP server today, you need to understand what changes before July 28 finalizes the spec.

I keep seeing people on X call this "MCP 2.0". It is not. The spec uses date versions, not semver. The official name is the 2026-07-28 specification, and it sits as a release candidate until the final freeze on July 28 2026. The ten-week window between now and then is for SDK maintainers and server authors to validate against real workloads.

The big shift is that MCP is going stateless. The current 2025-11-25 spec treats every client-server connection as a session with handshake, identifier, and lifecycle. The new spec rips most of that out at the protocol layer. Below I walk through what changed, what broke, and whether you should rush your migration or wait.

What is the MCP 2026-07-28 spec release candidate?

The 2026-07-28 release candidate is the next major version of the Model Context Protocol, locked on May 21 2026 and finalizing on July 28 2026. It introduces a stateless protocol core, a formal Extensions framework, the Tasks extension for long-running work, MCP Apps for server-rendered UIs, and OAuth-aligned authorization.

The official MCP roadmap calls this revision "the largest revision of the protocol since launch". Tier 1 SDK maintainers (the official Anthropic-maintained Python and TypeScript SDKs) are expected to ship support within the ten-week validation window. If you maintain a server or build agent infrastructure on top of MCP, this is the version you target next.

A subtle but useful detail: the MCP team shifted its 2026 roadmap from release-milestone organization to priority-area focus. Four priority areas drive the spec now: Transport Evolution and Scalability, Agent Communication, Governance Maturation, and Enterprise Readiness. Almost every concrete change in the 2026-07-28 spec maps directly to one of those four. That alignment matters because it tells you what to expect in the next spec drop too.

Why was the 2025-11-25 stateful protocol hard to scale?

The 2025-11-25 spec required every connection to start with an initialize/initialized handshake. The server returned a session identifier in an Mcp-Session-Id response header, and every subsequent request from that client had to carry the same header so the server could route it back to its session state.

That design is fine for a single-process MCP server running on a developer laptop. It is painful in production. The MCP roadmap calls the problem out directly: "Stateful sessions fight with load balancers, horizontal scaling requires workarounds." When you put a load balancer in front of stateful MCP servers you have three bad options.

You can run sticky sessions, which fail open whenever an instance restarts or scales down. You can share session state in Redis or a similar store, which adds a network hop and a single point of failure to every tool call. Or you can do deep packet inspection at the gateway, reading Mcp-Session-Id out of the header to manually route traffic, which forces every MCP client to know your private cluster topology.

In my own work running an MCP server behind a Vercel Function I hit this within a week. Functions are stateless by design. The first attempt to add MCP routing died on cold starts because the next invocation had no idea what session-id the client was carrying. Working around it meant pushing every session into Upstash Redis and eating the round trip on every tools/list call. Not fun.

The pattern is the same for any horizontally scaled deployment. Cloud Run, AWS Lambda, Kubernetes with HPA, even traditional VMs behind an L7 load balancer all run into the same wall. The old spec quietly assumed long-lived processes with shared memory. The new spec assumes nothing.

How does the stateless protocol core actually work?

The new spec removes the initialize/initialized handshake and the Mcp-Session-Id header from the base protocol. Each MCP request now carries everything the server needs to route it independently, and clients explicitly thread any state across calls themselves.

The headline change for ops folks: a stateless MCP server can sit behind a plain round-robin load balancer with no sticky sessions and no shared session store. According to the release notes, gateways can route traffic on the new Mcp-Method header instead of inspecting payloads, and clients can cache tools/list responses for as long as the server's ttlMs field permits. That last part matters because in production a tools/list call on a busy server can dominate the latency budget.

Here is the shape of the change in terms of request flow.

Before (2025-11-25):
client -> initialize -> server -> 200 + Mcp-Session-Id: abc
client -> tools/list (Mcp-Session-Id: abc) -> server (must own session abc)
client -> tools/call (Mcp-Session-Id: abc) -> same server instance

After (2026-07-28):
client -> tools/list -> load balancer -> server A (returns list + ttlMs)
client -> tools/call -> load balancer -> server B (different instance, same result)

You no longer need the same physical instance to handle both calls. That is the entire ballgame. In practice it means three things for your infrastructure: you can drop sticky session config from your load balancer, you can remove any shared Redis-based session store, and you can stop sending Mcp-Session-Id from your gateway routing rules.

The new Mcp-Method header is the small detail that pays off for gateway authors. Instead of parsing the JSON-RPC body to know whether a request is tools/list or tools/call, the gateway can read a single header and route by method. That lets you split tools/list (cacheable, idempotent) onto edge nodes and tools/call (mutating, sometimes expensive) onto warm origin nodes.

What do Extensions, Tasks, and MCP Apps add?

The 2026-07-28 spec formalizes Extensions as the way new capabilities ship outside the core protocol. The MCP team calls out Extensions as a deliberate move to keep the core small while still letting the ecosystem experiment. New capabilities propose themselves as Extensions first, prove production value, and only graduate into the base spec on the next date-stamped revision.

Two extensions matter most for new servers right now. The Tasks extension is built for long-running operations that need retries, expiry, and lifecycle tracking. If you have ever tried to wrap a 3-minute search index build inside a single MCP tool call and watched the client time out, Tasks fix that. The roadmap explicitly mentions "Tasks lifecycle refinement (retries, expiry policies)" as a priority for 2026.

The Tasks model looks roughly like this. Your tool call returns a task handle instead of a result. The client polls or subscribes to the task by id. The server keeps the task's state in whatever store you like (Redis, Postgres, S3), and the client decides how long it is willing to wait. The client and server never need to be in the same process for this to work. A different server instance can resume a task from its persistent state because the task id is the carrier, not a session.

MCP Apps are the second new extension. They let a server return server-rendered UI components instead of plain text or JSON payloads. The idea is that an MCP server for, say, a payments API can return a real card UI that the host renders inline. This is the closest MCP has come to giving servers presentation control, and it pulls the protocol closer to where Anthropic's Claude Skills and Claude Apps already live.

Both Extensions and Tasks shipped first as experimental features so the team could collect real-world feedback before locking them into a final spec. Treat them as production-ready in the RC window, but expect minor field renames before July 28.

What changes in authorization and error handling?

The new spec aligns authorization more closely with OAuth and OpenID Connect. The earlier spec left auth largely as an implementation detail, which meant every enterprise MCP deployment built its own bearer-token flow. The 2026-07-28 spec defines how OAuth flows interact with MCP transport so a single enterprise SSO setup covers all your MCP servers.

The roadmap lists "Governance Maturation" and "Enterprise Readiness" as priority areas, with audit trails, SSO auth, and gateway behavior as concrete deliverables. If you have been blocked on MCP rollout because security teams could not approve a custom auth flow, this is the change that unblocks you.

Error handling also tightens up. The error code for missing resources shifts from the proprietary -32002 to the JSON-RPC standard -32602. Looks like a small change. In practice it means any client that hard-coded -32002 in retry logic now silently swallows the error and retries forever on legitimate not-found responses. I have already seen this fail in a private SDK that hardcoded the old code. Catch both for the next year of mixed deployments.

A nice secondary effect is that monitoring tools that already understand JSON-RPC standard codes (and there are a lot of them) suddenly understand MCP traffic for free. You lose a small amount of MCP-specific signal in exchange for free integration with every JSON-RPC tracing tool out there. That is a good trade.

Which existing code breaks when you upgrade?

The breaking surface is small in lines of code but wide in impact. Here is what I am tracking across my own servers.

Anywhere your code asserts on Mcp-Session-Id will break. The header is no longer guaranteed and any session-based routing logic needs to come out of your gateway and your client. If you are running NGINX or an Envoy sidecar with rules on Mcp-Session-Id, those rules now do nothing. Worse, they may silently route ALL traffic to one origin because the default fallthrough rule kicks in.

Anywhere your client uses session state implicitly via the handshake will break. The new spec asks you to thread identifiers explicitly between tool calls. If you call tools/list and store the result keyed by session, you need to switch to keying by server URL plus ttlMs.

Anywhere your retry logic catches -32002 will silently misbehave. Change it to -32602 or, better, catch both for the next year of mixed deployments while clients catch up.

Anywhere your gateway does deep packet inspection on the body to route requests will break in a more positive direction. You can rip that logic out and rely on the new Mcp-Method header for routing decisions. Code you delete is code that cannot break in production.

If you are using a Tier 1 SDK (the Anthropic-maintained Python and TypeScript SDKs), the SDK will hide most of these changes from you within the ten-week validation window. If you are on a community SDK, check whether your maintainer is in the Tier 1 list before you plan a migration date. The SDK tier system is itself new to MCP and tells you which SDKs the spec maintainers actively coordinate with on breaking changes.

Should you migrate before July 28 or after?

It depends on whether you control both the client and the server. If you do, migrate as soon as the SDK you depend on ships RC support, which for Tier 1 should land within four to six weeks. The new protocol is friendlier to the production patterns you already want anyway.

If you ship a public MCP server consumed by clients you do not control, hold until July 28 and ship support for both spec versions on the same endpoint for at least a quarter. The spec's deprecation policy and the SDK tier system make dual support cheaper than it sounds, since both protocols can share the same handler code with a thin compatibility layer that reads the request and returns either a session-id (for old clients) or no session (for new ones).

The one case where you should rush is if you are running MCP in a Kubernetes deployment behind an L7 load balancer. The current setup probably has at least one band-aid (sticky sessions, Redis session store, deep packet inspection) that exists only because of the stateful protocol. Migrating lets you delete that code, and code you delete is code that cannot break in production.

There is also a clear case where you should wait. If your MCP server depends on a community SDK that is not in the Tier 1 list, you do not have a guarantee that the SDK will ship 2026-07-28 support before July 28 itself. Plan a quarter of slack. Do not promise a migration date until the SDK author publishes their own.

What does this mean for your MCP servers?

The 2026-07-28 spec is a clean win for anyone running MCP in production. The stateless core removes the awkward fit between MCP and modern serverless or horizontally scaled deployments, and the Tasks and MCP Apps extensions plug gaps that every real deployment has been working around with custom code.

The bigger lesson, though, is that MCP is starting to act like an open protocol with real production users, not a research experiment from Anthropic. Date-stamped versioned specs, an SEP process, formal SDK tiers, and a published roadmap with priority areas all push it in the direction of HTTP or LSP, not a vendor SDK. That is a healthy sign even if the immediate migration is annoying.

If you are starting a new MCP server this week, target the 2026-07-28 RC directly. If you have an existing one, start with deleting your Mcp-Session-Id routing rules and your shared session store. Most teams will find that the migration shrinks their MCP stack rather than grows it, which is the right direction for a protocol that is supposed to be the lowest-friction way to give an LLM access to tools.

For more on the new spec, see the official 2026-07-28 Release Candidate announcement, the 2026 MCP Roadmap, and the current 2025-11-25 specification for the baseline you are migrating from.

Keep Reading

How to Build a Stateless MCP Server for the 2026-07-28 Spec. The applied tutorial that ships with code once you understand the protocol shift this post covers.
Spring AI 2.0 MCP Annotations: From Tool to Production. How the Spring AI 2.0 abstractions sit on top of MCP and what they hide from you.
Claude Skills vs MCP vs Projects: Which One Should You Use?. When to pick MCP at all, given the other ways Claude exposes capabilities to agents.

PostgreSQL 18 Temporal Foreign Keys with Spring Boot JPA

Rabinarayan Patra — Thu, 21 May 2026 18:30:00 +0000

PostgreSQL 18 shipped temporal foreign keys. The kind of feature SQL standards committees promised back in SQL:2011 and most database vendors quietly ignored. Now it's in mainline PG and the Java ecosystem has almost no tutorials on how to use it from Spring Boot.

I went looking for "Spring Boot temporal foreign key" guides last week. The top results were 2018 Baeldung posts on hand-rolled validFrom/validTo columns with zero database-level constraints. Plenty of BETWEEN queries. Plenty of "remember to add an index". No one talks about PG18 yet. So I built a working example, hit every gotcha, and wrote it up.

This post walks the full path: what temporal FKs actually solve, the PostgreSQL 18 syntax, how to map range columns in Hibernate, the Spring Data repository patterns that work, and the ON DELETE behavior that will absolutely surprise you if you skip the docs.

What problem do temporal foreign keys solve?

A temporal foreign key enforces that a child row's time range fits entirely inside its parent row's time range, at the database level, on every insert and update. That's the part regular foreign keys can't do.

Take a classic example. An employee changes departments three times in five years. A project assignment references the employee. The business rule is: a project assignment can only exist during a period when the employee was actually employed.

The hand-rolled approach looks like this:

CREATE TABLE employees (
    emp_id BIGINT,
    valid_from DATE NOT NULL,
    valid_to DATE,
    PRIMARY KEY (emp_id, valid_from)
);

CREATE TABLE project_assignments (
    assignment_id BIGINT PRIMARY KEY,
    emp_id BIGINT NOT NULL,
    assignment_start DATE NOT NULL,
    assignment_end DATE,
    FOREIGN KEY (emp_id) REFERENCES employees(emp_id)
);

Every Spring shop I've worked at had a variation of this. And every one of them had bugs. Project assignments referencing employee IDs whose valid period ended six months ago. Manual BETWEEN checks in service layers that someone forgot to update. Audit failures during quarterly reviews. The data model lied about what it was.

PG18 fixes this at the constraint level. The constraint is the truth, not a service-layer hope.

How does PostgreSQL 18 implement WITHOUT OVERLAPS and PERIOD?

PG18 introduces two new clauses: WITHOUT OVERLAPS for primary and unique keys, and PERIOD for foreign keys. Both rely on range types and GiST indexes under the hood.

Here's the employees table redone the right way:

CREATE EXTENSION IF NOT EXISTS btree_gist;

CREATE TABLE employees (
    emp_id BIGINT NOT NULL,
    name VARCHAR(100) NOT NULL,
    department VARCHAR(50) NOT NULL,
    salary NUMERIC(10,2) NOT NULL,
    valid_period daterange NOT NULL,
    PRIMARY KEY (emp_id, valid_period WITHOUT OVERLAPS)
);

A few things worth pointing out.

The btree_gist extension is required because the primary key mixes a regular BIGINT column with a range column. PG needs a GiST index that can handle both, and btree_gist provides the btree operator support inside GiST. If you forget it, the CREATE TABLE will fail with a confusing operator error.

The valid_period column uses daterange, one of PostgreSQL's built-in range types. You can also use tstzrange for timestamp ranges or int4range for numeric ranges. The constraint creates a GiST index automatically. Try to insert two rows for the same emp_id with overlapping valid_period values and PG rejects it.

Now the project assignments table with a real temporal FK:

CREATE TABLE project_assignments (
    assignment_id BIGSERIAL PRIMARY KEY,
    emp_id BIGINT NOT NULL,
    project_name VARCHAR(100) NOT NULL,
    assignment_period daterange NOT NULL,

    FOREIGN KEY (emp_id, PERIOD assignment_period)
        REFERENCES employees (emp_id, PERIOD valid_period)
);

The PERIOD keyword tells PG that the last column is a range. The check is not equality. The check is containment: the parent's matching rows must, in combination, fully cover the child's range. If the employee's valid_period ends June 1 2024 and the project assignment runs March 1 to August 1 2024, the insert fails because June 1 to August 1 has no parent row covering it.

You can verify this with a deliberate bad insert:

INSERT INTO employees (emp_id, name, department, salary, valid_period)
VALUES (1, 'Alice', 'Engineering', 80000, daterange('2024-01-01', '2024-06-01'));

INSERT INTO project_assignments (emp_id, project_name, assignment_period)
VALUES (1, 'Migration', daterange('2024-03-01', '2024-08-01'));
-- ERROR: insert or update on table "project_assignments" violates foreign key constraint

The constraint catches it. No service code needed.

How do you map daterange columns in Hibernate?

Hibernate 6 added native support for PostgreSQL range types through PostgreSQLRangeJdbcType, but the cleanest path for a Spring Boot app is still the hypersistence-utils library. It's the rebranded version of what most of us used as hibernate-types-52 for years, maintained by Vlad Mihalcea.

Add the dependency to your pom.xml:

<dependency>
    <groupId>io.hypersistence</groupId>
    <artifactId>hypersistence-utils-hibernate-63</artifactId>
    <version>3.10.7</version>
</dependency>

If you're on Spring Boot 3.5+, you'll be on Hibernate 6.6, so use the hypersistence-utils-hibernate-63 artifact. Older Spring Boot 3.x versions use -62. The version numbers track Hibernate ORM, not Spring Boot.

Now the entity:

import io.hypersistence.utils.hibernate.type.range.Range;
import io.hypersistence.utils.hibernate.type.range.PostgreSQLRangeType;
import jakarta.persistence.*;
import org.hibernate.annotations.Type;

import java.math.BigDecimal;
import java.time.LocalDate;

@Entity
@Table(name = "employees")
@IdClass(EmployeeId.class)
public class Employee {

    @Id
    @Column(name = "emp_id")
    private Long empId;

    @Id
    @Type(PostgreSQLRangeType.class)
    @Column(name = "valid_period", columnDefinition = "daterange")
    private Range<LocalDate> validPeriod;

    @Column(nullable = false)
    private String name;

    @Column(nullable = false)
    private String department;

    @Column(nullable = false)
    private BigDecimal salary;

    // getters, setters, constructors
}

A few things to flag.

The @IdClass(EmployeeId.class) is needed because the primary key is composite. The EmployeeId class is a plain Java record or class with the two ID fields and equals/hashCode.

public record EmployeeId(Long empId, Range<LocalDate> validPeriod) implements Serializable {}

The @Type(PostgreSQLRangeType.class) annotation is what makes Hibernate emit and read daterange correctly. The columnDefinition = "daterange" part is what makes JPA's schema generation produce the right column type if you let JPA create the schema. In production, you should use Flyway or Liquibase, not JPA schema generation, but it's worth being explicit either way.

You construct ranges like this:

Range<LocalDate> period = Range.closedOpen(
    LocalDate.of(2024, 1, 1),
    LocalDate.of(2024, 6, 1)
);

closedOpen matches PostgreSQL's [) notation, which is the most common range form for temporal data. Half-open intervals make adjacent ranges easy to reason about: [Jan 1, Jun 1) and [Jun 1, Dec 1) are adjacent, not overlapping.

through hypersistence-utils to PostgreSQL daterange" width="799" height="452">

How do you write the entity and repository?

Spring Data JPA does most of the work, but you need a custom query for the overlap check at the application level. Database constraints catch invalid inserts, but the app still needs to ask "who was employed during this period?"

The repository:

public interface EmployeeRepository extends JpaRepository<Employee, EmployeeId> {

    @Query(value = """
        SELECT *
        FROM employees
        WHERE emp_id = :empId
          AND valid_period && :period
        """, nativeQuery = true)
    List<Employee> findOverlapping(
        @Param("empId") Long empId,
        @Param("period") String period
    );
}

The && operator is PostgreSQL's range-overlap operator. You pass the range as a string in PG range literal form: [2024-01-01,2024-06-01). JPA doesn't have a native range-binding mechanism, so the string approach is the pragmatic move. If you want strong typing, Vlad's library offers Range.toString() which formats correctly.

Here's a service method that finds the employee record valid for a given date:

@Service
public class EmploymentService {

    private final EmployeeRepository repo;

    public EmploymentService(EmployeeRepository repo) {
        this.repo = repo;
    }

    public Optional<Employee> findAt(Long empId, LocalDate at) {
        String singleDay = String.format("[%s,%s]", at, at);
        return repo.findOverlapping(empId, singleDay).stream().findFirst();
    }
}

For the project assignment side, the insert just works. Hibernate sends the daterange, PG checks the temporal FK, and if the assignment period isn't fully covered by some employee period, the transaction rolls back.

@Transactional
public ProjectAssignment assign(Long empId, String projectName, Range<LocalDate> period) {
    ProjectAssignment pa = new ProjectAssignment();
    pa.setEmpId(empId);
    pa.setProjectName(projectName);
    pa.setAssignmentPeriod(period);
    return assignmentRepo.save(pa);
}

If the period extends past the employee's validity, you get a DataIntegrityViolationException wrapping the PG error. Catch it where your error handling needs it.

What are the gotchas with ON DELETE and temporal foreign keys?

This is the one that will burn you if you skip the docs. PostgreSQL 18 does not support CASCADE, RESTRICT, SET NULL, or SET DEFAULT referential actions on temporal foreign keys. Only NO ACTION is allowed.

From the official PG18 CREATE TABLE docs: "In a temporal foreign key, this option is not supported." That sentence appears under every action except NO ACTION.

What does this mean in practice? If you delete an employee row that has dependent project assignments, PG raises a foreign key violation. You have to delete the assignments first, manually, in application code or in a database trigger you write yourself.

-- This will fail at the second statement
DELETE FROM employees WHERE emp_id = 1;
-- ERROR: update or delete on table "employees" violates foreign key constraint

The workaround patterns I've seen:

The first is application-level deletion. Spring service methods that delete child rows before parent rows, wrapped in a @Transactional boundary. This is fine for small graphs, but it doesn't scale to deep hierarchies.

The second is soft delete on the parent. Add a deleted_at column, never actually delete rows, and let the temporal FK stay intact forever. Most enterprise systems do this anyway for audit reasons.

The third is to flip the model: instead of deleting the parent, you close the parent's period by updating valid_period to end at today's date. Future child inserts will fail. Existing child rows stay valid because their periods were covered when they were created.

The third approach is closest to the spirit of temporal modeling. You don't lose history. You just declare "this record stopped being valid at this point" and let the constraints enforce that going forward.

If you absolutely need cascading deletes, you can write a trigger that does the deletion manually before the parent delete fires. But at that point you're rebuilding what the standard wanted to give you, and the SQL spec authors decided cascade semantics on overlapping periods were too ambiguous to specify. They might be right.

When should you NOT use temporal foreign keys?

Temporal foreign keys are powerful, and like most powerful features they're easy to overuse. I've seen teams reach for them in places where regular FKs would be simpler and just as correct.

Skip temporal FKs when:

You only need audit history. If the question is "what changed when?" and not "what was the state of the world on date X?", a separate audit log table with regular FKs is simpler. Frameworks like Hibernate Envers handle this well.

The child rows don't have an independent time dimension. If a project assignment is just "associated with employee 1 forever", you don't need temporal FKs. A regular FK with a created_at timestamp is fine.

You're modeling a single current state. CRUD apps where the latest row is the only thing that matters don't need temporal modeling. Add a valid_period column and you've created complexity you'll have to pay for in every query.

You can't pay the GiST index cost. GiST indexes are slower for point lookups than btree indexes. For high-throughput single-row reads, you'll feel it. Benchmark first.

When the model genuinely is temporal, the constraint-enforced version is a huge improvement over the hand-rolled version. The number of bugs you avoid by having PG check every insert is real. The cost of writing the queries against ranges instead of timestamps is real too, but it's a one-time cost. The bugs are forever.

Conclusion

PostgreSQL 18 temporal foreign keys are one of the most under-discussed major-version features I've seen in a while. The Spring Boot ecosystem has barely caught up. If you're modeling employment, contracts, pricing tiers, policies, or anything else where state has duration, the new WITHOUT OVERLAPS and PERIOD clauses are worth learning even if you don't ship them tomorrow.

The piece I want more people to understand: this changes what your database can be the source of truth for. Before PG18, "this assignment must fall inside an employment period" was a service-layer concern that drifted out of sync. Now it's a constraint. The database tells the truth.

For more on the PG18 release, see the PostgreSQL 18.0 release notes, the Neon writeup on temporal constraints, and the CREATE TABLE syntax docs.

Keep Reading

Spring Boot Testcontainers Guide. Real PG18 in tests beats mocked databases for catching constraint bugs early.
Hibernate Lazy Init Guide. The other Hibernate gotcha that bites every Spring team.
PgBouncer Survival Guide. Connection pooling matters more when GiST indexes are doing real work.

Next.js 16.2 AGENTS.md and next-browser: A Hands-On Guide

Rabinarayan Patra — Tue, 28 Apr 2026 18:30:00 +0000

I run Claude Code on my Next.js portfolio every day. For the last year my routine has been the same: paste the relevant Next.js 16 doc into chat, watch the agent write something that worked in Next.js 13, correct it, paste another doc, repeat. The agent's training data was stale, the context window was precious, and I was the middleman.

Next.js 16.2 quietly killed that routine. Shipped on March 18, 2026 by Jude Gao, Jimmy Lai, Tim Neutkens and the rest of the Next.js team, the release ships AGENTS.md by default, bundles the entire Next.js docs as plain Markdown inside node_modules/next/dist/docs/, and adds an experimental @vercel/next-browser CLI that lets agents inspect a running app through shell commands. Vercel ran their internal evals and saw 100% pass rate with AGENTS.md vs 79% with the best skill-based setup. That is a big enough gap to change how I scaffold projects.

This post walks through what actually shipped, how to add it to an existing project, and what I changed in my own workflow after upgrading rabinarayanpatra.com to 16.2.

What is AGENTS.md in Next.js 16.2?

AGENTS.md is a Markdown file at the root of a Next.js project that tells AI coding agents to read the version-matched docs bundled inside node_modules/next/dist/docs/ before writing any code. It is not a skill, it is not a plugin, and it is not loaded on demand. It is always-on context that any agent respecting the AGENTS.md convention will pick up at the start of every turn.

The default file that create-next-app generates is small. Here is the shape of it:

<!-- BEGIN:nextjs-agent-rules -->

# Next.js: ALWAYS read docs before coding

Before any Next.js work, find and read the relevant doc in `node_modules/next/dist/docs/`. Your training data is outdated. The docs are the source of truth.

<!-- END:nextjs-agent-rules -->

The BEGIN and END comment markers delimit the Next.js-managed section. Future codemods will only rewrite what is inside those markers, so anything you add outside stays yours. That is a small design choice with a big payoff, because it means you can keep your own agent rules next to the framework's without fighting merge conflicts.

The second piece is the bundled docs themselves. The next npm package now ships the full doc tree as plain Markdown files. Open node_modules/next/dist/docs/ in your editor and you will see the same content as nextjs.org, organized by section. A compressed index file is also shipped at around 8 KB, an 80% reduction from the raw 40 KB of full docs, which is what the agent reads first to find the right file to pull into context.

Third, on projects already set up for Claude Code, there is a tiny convention link:

@AGENTS.md

The @ directive tells Claude Code to include the contents of AGENTS.md whenever it loads CLAUDE.md. So the bootstrap chain becomes CLAUDE.md pulls in AGENTS.md, AGENTS.md tells the agent to read node_modules/next/dist/docs/ whenever Next.js work is happening, and the agent writes code against the real 16.2 API rather than a memory of Next.js 13.

How do you add AGENTS.md to an existing Next.js project?

On Next.js 16.2 or later, you already have the docs on disk. You just need to create the two files yourself or let the codemod do it. The codemod is the faster path:

npx @next/codemod@latest agents-md

That scaffolds AGENTS.md with the managed directive block and creates or updates CLAUDE.md with the @AGENTS.md include. I ran it on the portfolio and it was a one-second change plus two new files in the diff.

If you are on an older version of Next.js, upgrade first:

npx @next/codemod@canary upgrade latest

Then re-run the agents-md codemod. The upgrade is where the doc bundle actually lands on disk, so you need 16.2 for the whole flow to work.

The part I liked most is the escape hatch. If your project already has a sprawling AGENTS.md with your own conventions, you can drop the managed block into it and keep everything else. The codemod respects existing files and only touches what is inside the markers. That matters for teams who have been writing their own agent rules for months.

One pitfall I hit on my first attempt: my .gitignore had node_modules/ ignored (obviously), but Claude Code was still happy to read from it, since it is a local file read, not a git operation. So you do not need to commit the docs, you just need the package installed. CI builds, however, need to run npm install before an agent can use the docs, which is the usual order anyway.

What does the @vercel/next-browser CLI actually do?

@vercel/next-browser is an experimental CLI that wraps a persistent Chromium instance with React DevTools pre-loaded and exposes browser data through shell commands. Instead of an agent trying to understand a DevTools panel it cannot see, the agent runs a shell command, gets back structured text, and reasons about the output.

You install it as a skill:

npx skills add vercel-labs/next-browser

Then trigger it inside an agent that supports skills by typing /next-browser. Claude Code and Cursor both work. The first run boots a Chromium instance you do not see, loads React DevTools into it, and holds the session open across commands.

At release the feature set covers five buckets. Component trees with props, hooks, state, and source-mapped file locations. PPR shell analysis, which identifies what is static and what is blocking. Errors and logs from the dev server. Network activity since the last navigation, including server actions. And visual capture with screenshots or loading filmstrips.

The concrete example in the release post is my favorite, because it shows the workflow end-to-end. You have a blog post page with a visitor counter:

export async function generateStaticParams() {
  const posts = await getAllPosts();
  return posts.map((post) => ({ slug: post.slug }));
}

export default async function BlogPost({ params }) {
  const post = await getPost(params.slug);
  const views = await getVisitorCount(params.slug); // per-request

  return (
    <article>
      <h1>{post.title}</h1>
      <span>{views} views</span>
      <div>{post.content}</div>
    </article>
  );
}

Every slug is enumerated ahead of time, so the post content should prerender at build. But getVisitorCount runs on every request and sits at the top level, which drags the entire page out of the static shell. The user sees a loading skeleton instead of the post content streaming in.

An agent can diagnose this by locking PPR mode and inspecting the shell:

next-browser ppr lock
next-browser goto /blog/hello

With PPR locked, only the static shell renders. In this case the shell is the loading skeleton, because nothing from the page made it in. Running ppr unlock gives the agent a structured report:

# PPR Shell Analysis
# 1 dynamic hole, 1 static

blocked by:
  - getVisitorCount (server-fetch)
    owner: BlogPost at app/blog/[slug]/page.tsx:5
    next step: Push the fetch into a smaller Suspense leaf

The agent now knows what the blocker is, where it lives, and what to do. It wraps the counter in a Suspense boundary:

export default async function BlogPost({ params }) {
  const post = await getPost(params.slug);

  return (
    <article>
      <h1>{post.title}</h1>
      <Suspense fallback={<span>... views</span>}>
        <VisitorCount slug={params.slug} />
      </Suspense>
      <div>{post.content}</div>
    </article>
  );
}

Run ppr lock again and the shell has grown. The post content prerenders instantly, and only the view count falls back to the Suspense placeholder. The agent did that without ever opening a browser window.

The thing I keep coming back to is that the CLI is designed around one-shot commands against a persistent session. That matches how LLM tool-calling works today. The agent does not manage browser state, the CLI does. The agent just asks questions and parses replies, which is exactly the interaction pattern that works for a model.

How does the dev server lock file help AI agents?

Next.js 16.2 writes the running dev server's PID, port, and URL into .next/dev/lock. When a second next dev starts in the same directory, Next.js reads the lock file and prints an actionable error instead of a generic port-conflict message:

Error: Another next dev server is already running.

- Local: http://localhost:3000
- PID: 12345
- Dir: /path/to/project
- Log: .next/dev/logs/next-development.log

Run kill 12345 to stop it.

On paper this is quality-of-life for humans. In practice, this is the single change that saves me the most time with Claude Code.

Before 16.2, my workflow was: I start the dev server in a pane, Claude Code spawns its own next dev to check something, the command hangs because port 3000 is taken, Claude Code retries on another port, I get a second server I do not want. Now the agent gets a clean error, a PID to kill, a URL to connect to, and a log path to tail. It makes the right call the first time.

The lock file also prevents two next build processes from running at once, which could otherwise corrupt build artifacts. That is a genuine bug I have seen in CI where a re-run was queued before the first finished. Now the second run refuses to start.

How do you forward browser logs to the terminal?

By default, Next.js 16.2 forwards browser errors to the dev terminal. You do not have to switch to the browser console to see client-side errors, which is another quality-of-life win for agents who cannot open a DevTools panel at all.

The level is configurable:

const nextConfig = {
  logging: {
    browserToTerminal: true,
    // 'error': errors only (default)
    // 'warn': warnings and errors
    // true: all console output
    // false: disabled
  },
};

export default nextConfig;

I ran this at true for a week and it was too noisy for a typical debugging session. I rolled it back to 'warn' which is the right default for me. Errors alone is usually too narrow, because half the client-side issues I chase start as warnings that the agent would have caught earlier with a wider filter.

Pairing this with the agent DevTools is the real win. The agent gets errors in the terminal, runs next-browser for a closer look, fixes the code, and moves on. No browser console, no screenshots to interpret, no back-and-forth with me asking what the page looked like.

Why does Vercel say AGENTS.md beat skills in their evals?

The numbers from Vercel's internal eval are worth quoting straight. They tested four configurations against a suite of Next.js 16 APIs that did not exist in model training data, like 'use cache', cacheTag(), forbidden(), and proxy.ts:

Configuration	Pass rate
Baseline (no docs)	53%
Skill (default invocation)	53%
Skill with explicit instructions	79%
AGENTS.md docs index	100%

The skill with default invocation matched baseline exactly. Vercel's explanation for that is brutal: "In 56% of eval cases, the skill was never invoked." The agent did not know it needed to look something up, so it did not.

Explicit instructions pushed skills to 79%, which is a real improvement, but it took careful prompt wording to get there. Phrasing like "You MUST invoke" caused agents to anchor on the docs and miss project context. "Explore project first, then invoke skill" was better. That kind of prompt sensitivity is not something I want to maintain for a team.

AGENTS.md hit 100% across build, lint, and test eval categories. The authors called out the mental model: the goal is to shift agents "from pre-training-led reasoning to retrieval-led reasoning." Always-on context wins over on-demand retrieval because there is no decision point the agent can get wrong.

That matches my experience. The moments I lost the most time with Claude Code were the moments it was confidently wrong, using old APIs it remembered from training. It did not ping the docs because it did not know it needed to. AGENTS.md removes that failure mode by making the docs non-negotiable.

What changes did Next.js 16.2 make to rendering performance?

The agent story is the headline, but 16.2 also ships a big performance jump that is easy to miss. The team landed a change in React (PR #35776) that replaces JSON.parse with a reviver callback with JSON.parse followed by a recursive walk in pure JavaScript. The result is up to 350% faster RSC payload deserialization and 25% to 60% faster real-world server rendering.

The root cause is a V8 quirk. JSON.parse with a reviver crosses the C++/JavaScript boundary once per key-value pair, and even a no-op reviver makes parsing around 4x slower than without one. Replacing that with a two-step parse-then-walk eliminates the per-key cost.

The measured numbers are the kind of data I trust because they come from real apps:

Workload	Before	After	Speedup
1000-item Server Component table	19ms	15ms	26%
Server Component with nested Suspense	80ms	60ms	33%
Payload CMS homepage	43ms	32ms	34%
Payload CMS with rich text	52ms	33ms	60%

You do not need to change any code. Upgrade to 16.2 and react@latest and the speedup lands. The heavier your RSC payload, the bigger the win, which is why the rich-text case hits 60%.

Next.js 16.2 also makes ImageResponse 2x faster for basic images and up to 20x faster for complex ones, with the default font switched from Noto Sans to Geist Sans. Dev startup is around 87% faster than 16.1 on the default application, so the time between next dev and a ready localhost shrank noticeably on my machine.

Does AGENTS.md replace Claude Code skills entirely?

No, and I do not think it should. AGENTS.md and skills solve different problems.

AGENTS.md is for always-on framework context. Your agent needs to know Next.js 16 every time it writes a Next.js component. That is not an on-demand concern, it is a default concern. Putting it in AGENTS.md removes the decision point about whether to fetch the docs, which is exactly the decision agents are bad at.

Skills are for scoped, opt-in capabilities. A skill that runs a specific CLI, calls a private API, or triggers a deploy is something you want the agent to invoke deliberately. The decision point is the feature. You do not want the agent triggering your prod deploy on every turn.

The Vercel team made the right call putting framework docs into AGENTS.md and keeping the next-browser debugger as a skill you trigger with /next-browser. The debugger is a scoped capability. The framework docs are ambient context. Matching each tool to the right mechanism is the actual lesson here.

My working rule, after a week of running both on the portfolio: if your agent should consult it every time, put it in AGENTS.md. If your agent should consult it sometimes, make it a skill.

What does this mean for the next year of framework design?

Next.js 16.2 is the first mainstream framework release where the primary design target is an AI coding agent, not a human developer. The default scaffolding exports a file the human may never read. The docs are shipped as Markdown because that is what parses cleanly for a model. The dev server writes a lock file so another process can recover without a human. The experimental DevTools are a shell command interface because that is what LLMs can drive.

This is not a future-looking take. It is already in create-next-app@latest. And the concrete UX win for me was small but sharp: I stopped pasting docs into chat. That one behavior change saved me an hour a week. Scaled across a team of developers all running agents all day, the time savings compound fast.

The open question is how many frameworks follow. Spring, FastAPI, Rails, Django, Laravel, every major framework has the same training-data-staleness problem Next.js just solved. I expect the next wave of releases to ship their own AGENTS.md conventions, bundled docs, and agent-friendly CLI wrappers. Vercel's eval numbers make the business case too strong to ignore.

For more on this release, see the Next.js 16.2 blog post, the Next.js 16.2 AI Improvements post, and Vercel's AGENTS.md outperforms skills eval writeup. The RSC payload perf change is React PR #35776 if you want to read the actual diff.

Keep Reading

Building a Modern Docs Generator with Next.js 16. Where I first went deep on Next.js 16's App Router and how I think about docs infrastructure.
Hello Proxy in TypeScript and Next.js 16. The middleware/proxy rename that landed in 16.0, relevant background for anything using proxy.ts.
Replacing useEffect Data Fetching with Server Actions. Server-side patterns that pair naturally with the 16.2 rendering improvements.
Vercel AI Gateway Deep Dive. The other side of the Vercel AI story, if you want the provider routing and observability angle.