PANews is a crypto and Web3 news platform.

Our previous backend was written in Go, deployed on Kubernetes, and backed by MySQL.

There was nothing wrong with that stack in isolation. Go is reliable. Kubernetes is powerful. MySQL is mature. The problem was not that the technologies were bad. The problem was the cost structure they created for our business.

PANews is a content-heavy product. Most traffic is read-heavy, bursty, and repetitive. For that kind of workload, we were carrying too much infrastructure responsibility ourselves: application clusters, database instances, connection pools, scaling, backups, failover, monitoring, and incident response.

The database bill was thousands of dollars per month, but the operational experience did not feel proportional to the cost. In the early days, when we used an IDC-hosted database, the most painful part was not a single outage. It was that every instability became our problem to diagnose. When the database crashed or connections became unstable, we had to figure out whether the issue was the machine, the network, the database process, the connection pool, or a query pattern in the application.

Eventually, we made a deliberate architectural simplification:

• We moved from self-managed MySQL to Prisma Postgres.
• We moved the backend runtime to Cloudflare Workers.
• We put Cloudflare Hyperdrive between Workers and Postgres.
• We used Hyperdrive cache for public read paths, while keeping a no-cache path for strong consistency.

The result was direct: our database cost dropped from thousands of dollars per month to roughly $400 per month.

This was not just “switching to a cheaper database.” The important change was that the database stopped carrying work it should never have been responsible for in the first place.

Expensive Databases Are Often a Symptom

Before the migration, the database was handling three different kinds of pressure.

The first kind was legitimate read and write traffic: publishing articles, updating configuration, changing user state, running admin operations. That is real database work.

The second kind was repeated public reads: home feeds, article lists, article pages, rankings, columns, recommendations. These requests are frequent, but the underlying data changes much less often than the traffic hits them.

The third kind was connection pressure from the runtime model. In a Kubernetes setup, we maintained service-side connection pools and provisioned capacity around peak behavior. In a serverless and edge runtime like Cloudflare Workers, direct database access can amplify connection setup, TLS, authentication, and network round trips if there is no layer in between.

The second and third kinds of pressure were not caused by business complexity. They were architecture cost.

For a content platform, most public reads do not need millisecond-level strong consistency. A home feed, an article list, or a related-articles block can usually tolerate a few seconds of eventual consistency. If every one of those requests goes directly to the database, the database is effectively being used as a cache.

That is an expensive cache.

When traffic grows under that model, you buy a bigger database, more connections, more headroom, and more operational complexity. But a lot of that money is not being spent on true business writes or genuinely fresh reads. It is being spent on repeated reads and connection bursts.

Managed Databases Remove Operational Burden, Not Read Amplification

Prisma Postgres solved the database maintenance problem for us.

What we wanted was not an impressive database architecture. We wanted standard Postgres, predictable pricing, reliable connectivity, backups, and fast support when something went wrong.

In the early Prisma Postgres adoption period, we did run into a few database crashes and stability issues. The difference was that these incidents did not become a long-term self-maintenance burden. Nurul from the Prisma team was extremely responsive, helped us investigate the issues, and pushed improvements forward.

That experience clarified what “managed” really means.

Managed does not mean infrastructure will never fail. It means that when infrastructure fails, the product team does not have to debug all the way down from IDC machines, network paths, database processes, and connection pool behavior. The platform team owns the lower layers, and the application team can focus on access patterns, cache boundaries, and business consistency.

But a managed database alone does not solve the entire cost problem.

If every public read still goes back to the database, then you have only moved from “self-managed database serving repeated reads” to “managed database serving repeated reads.” Operations get easier, and cost may improve, but the pressure model has not fundamentally changed.

The real shift came from Hyperdrive cache.

Hyperdrive Changed the Database Pressure Model

Hyperdrive sits between Cloudflare Workers and the database. For us, it provides two important capabilities: connection pooling and query caching.

Connection pooling means every Worker request does not have to become direct database connection pressure. Without a layer like Hyperdrive, each Worker invocation that talks directly to the database may pay for TCP, TLS, authentication, and database-level setup. Hyperdrive changes that path: Workers connect to Hyperdrive, while Hyperdrive maintains pooled connections closer to the database.

Query caching means repeated public reads do not always have to become database queries. Hyperdrive can cache eligible read queries, while writes and uncacheable queries still go to the origin database.

In production, we use two database paths:

• PG_CACHE: the default path for public reads, with Hyperdrive cache enabled.
• PG_NO_CACHE: the strong-consistency path for admin, write-after-read checks, debugging, and data that must be fresh.

This split matters more than “turning on cache.”

Caching everything would be dangerous. Admin screens, permissions, sessions, billing, configuration, and write-after-read validation must not accidentally read stale data. But forcing all public traffic through the strongest consistency path is also wasteful.

The real design is a consistency boundary:

• Public reads default to the cached path.
• Strong reads must be explicit.
• Writes and write-after-read checks do not depend on cache.
• Critical semantics are not sacrificed to save money.
• A minority of strong-consistency cases should not force the whole system onto the most expensive path.

Conceptually, it is as simple as this:

function databaseBinding(env: Env, strongRead: boolean) {
  return strongRead ? env.PG_NO_CACHE : env.PG_CACHE;
}

The code is not the point. The direction is the point: default to the lower-cost path, then explicitly upgrade consistency only when the business semantics require it.

Production Data: Nearly One Billion Hyperdrive Queries in 31 Days

Our production PG_CACHE Hyperdrive configuration points to Prisma Postgres. Cache is enabled, stale_while_revalidate is set to 30 seconds, and origin_connection_limit is 60. We did not set an explicit max_age, so it follows Cloudflare's documented default of 60 seconds.

As of 2026–07–10 00:06:30 Asia/Shanghai, the production Hyperdrive metrics looked like this:

WindowHyperdrive querieshit + clienthitHit-class ratioAvg connection latencyAvg query latencyResult bytes24h32,141,84922,235,68769.2%59ms67ms557GB7d218,892,655151,211,99669.1%12ms20ms3.57TB31d997,424,191684,811,98568.7%5ms12ms14.84TB

hit and clienthit are hit-class statuses we saw in Cloudflare GraphQL metrics. Cloudflare's public documentation currently explains statuses such as hit, miss, and uncacheable, but does not fully document clienthit, so I am not assigning extra semantics to it here. I treat hit + clienthit simply as the hit-class count reported by Cloudflare metrics.

The important takeaway is simple: over the last 31 days, Hyperdrive processed almost one billion database-related requests, and roughly 685 million of them were in hit-class states. If all of that traffic had gone directly to the database, the required database CPU, I/O, connection capacity, and tail headroom would have looked very different.

The connection pool metrics are also useful:

WindowAvg open connectionsObserved peak open connectionsAvg waiting clientsPeak waiting clients24h2.78121.39619577d2.25120.235295731d2.69120.12511061

The 31-day average open connection count was only 2.69, while peak waiting clients reached 1061. That tells us two things at the same time: the average state is healthy, but tail pressure still exists.

This is why platform features are not enough on their own. Application-level details still matter.

TTL Should Follow Business Semantics

Cache TTL should not be a global guess.

Longer TTL reduces database pressure, but increases the chance of stale data. Shorter TTL preserves freshness, but gives up some cache benefit. The right answer depends on the business semantics of each endpoint.

A simple split can look like this:

const CACHE_TTL_SECONDS = {
  homeFeed: 5,
  articleList: 10,
  articleDetail: 30,
  relatedArticles: 60,
  rankings: 300,
} as const;

The home feed and article lists need shorter windows because users care more about fresh content there. Related articles, rankings, and recommendation blocks can usually tolerate longer windows. Admin, permissions, sessions, and write-after-read flows should not use the cached path.

Hyperdrive provides the database-level caching layer, but the application still has to produce stable query shapes and choose the right access path.

Turning on cache is not the same thing as getting a high cache hit rate.

Stable Query Shape Is Cache Strategy

Cache hit rate depends heavily on query shape.

If a query uses NOW(), RANDOM(), dynamic SQL fragments, or millisecond-level timestamps, it becomes much harder to reuse cached results. Cloudflare's documentation also notes that PostgreSQL functions such as NOW() can affect cacheability.

This is not ideal for a public feed:

select id, title, published_at
from articles
where status = 'published'
  and published_at <= now()
order by published_at desc
limit 20;

A more cache-friendly approach is to bucket time in the application layer:

function timeBucket(seconds: number) {
  return new Date(Math.floor(Date.now() / (seconds * 1000)) * seconds * 1000);
}

Then pass the bucketed timestamp as a query parameter:

select id, title, published_at
from articles
where status = 'published'
  and published_at <= $1
order by published_at desc
limit 20;

A 5-second, 10-second, or 30-second time bucket sounds small. On a high-frequency public read path, it directly affects cache hit rate, origin query volume, and tail latency.

Reduce CPU Time on Public Reads

After database cost goes down, another cost often becomes more visible: compute time at the edge.

Public endpoints should do as little unnecessary work as possible:

• Select only the fields you need.
• Avoid deep-copying large objects.
• Avoid formatting timestamps repeatedly inside loops.
• Do not fetch large result sets just to sort, filter, and trim them in application code.
• Make SQL return a shape close to the API response.
• Keep JSON payloads small.

For example, a public article list should not fetch full article records, authors, tags, and metrics, then reshape everything in application code. The query should already be close to the response:

select
  id,
  title,
  cover_url as "coverUrl",
  published_at as "publishedAt"
from articles
where status = 'published'
  and published_at <= $1
order by published_at desc
limit 20;

The thinner the application layer, the lower the CPU time and the more stable the tail latency. Edge runtime is not a reason to do more work per request. It is a reason to finish each request quickly.

Reduce Round Trips

Tail latency often comes from sequential database round trips, not from one obviously slow SQL query.

This pattern is expensive:

const article = await getArticle(id);
const author = await getAuthor(article.authorId);
const tags = await getTags(id);

If the data is tightly related, fetch it in one query or at least parallelize independent queries.

For an article page, author and tags can often be fetched together:

select
  a.id,
  a.title,
  u.name as "authorName",
  coalesce(json_agg(t.name) filter (where t.id is not null), '[]') as tags
from articles a
left join users u on u.id = a.author_id
left join article_tags at on at.article_id = a.id
left join tags t on t.id = at.tag_id
where a.id = $1
group by a.id, u.name;

This is not about writing clever SQL for its own sake. It is about reducing network round trips. In a Workers-to-regional-database path, each extra round trip directly increases tail latency.

Scope Database Clients to Requests

When using Hyperdrive from Workers, do not create a database client in global scope, and do not add another global driver-level connection pool.

Cloudflare recommends creating the client inside the request handler. Hyperdrive maintains the underlying pool to the database. Worker-to-Hyperdrive client connections are cleaned up with the invocation lifecycle.

Conceptually:

import { Client } from 'pg';

export default {
  async fetch(_request: Request, env: Env) {
    const client = new Client({
      connectionString: env.PG_CACHE.connectionString,
    });

    await client.connect();

    const result = await client.query(
      `
      select id, title, published_at
      from articles
      where status = 'published'
      order by published_at desc
      limit 20
      `,
    );

    return Response.json(result.rows);
  },
};

The important part is not manually holding a database connection forever. In Workers with Hyperdrive, Hyperdrive owns the lower-level database pool. Application code should avoid global clients, extra connection pools, long transactions, and slow request lifecycles.

For local scripts and one-off operational tasks, the rule is different. If a script connects directly to the database, close the connection explicitly:

const client = new Client({ connectionString });
await client.connect();

try {
  await client.query('select 1');
} finally {
  await client.end();
}

Worker request handling and local operational scripts are different environments. Hyperdrive should pool database connections for Workers. Scripts should clean up after themselves.

Keep Transactions Short

The connection pool metrics showed healthy averages, but they also showed tail pressure. One common cause is long connection occupancy.

Long transactions, slow queries, external API calls inside transactions, and heavy application computation while holding a connection all increase waiting clients.

Keep transactions short. Put only the database operations that must be atomic inside the transaction. External requests, AI calls, object storage, search indexing, push notifications, and other side effects should happen outside the transaction or move to asynchronous jobs.

This is a basic rule, but it has a real effect on tail latency and connection pool health.

What Actually Changed

The core lesson from this migration is not “Postgres is cheaper than MySQL” or “Workers are better than Kubernetes.”

The real change was this:

From self-managed infrastructure and a database absorbing all read traffic

>

To managed Postgres, edge connection pooling, controlled caching, and explicit strong-consistency paths

The database stores facts.

Hyperdrive handles connection reuse and public read caching.

Workers serve requests close to users.

The application decides which reads need strong consistency and which reads can tolerate short eventual consistency.

The result was clear:

• Database cost dropped from thousands of dollars per month to roughly $400.
• IDC database instability and manual maintenance stopped being a daily concern.
• Public read traffic no longer directly determined database size.
• Over the last 31 days, about 68.7% of Hyperdrive query states were hit-class states.
• The team stopped spending energy on Kubernetes, database instances, and connection incidents.

My current view on database cost reduction is simple:

Do not make the database act as your cache. Do not make a small product team act as a database operations team. Do not force every request onto the most expensive consistency path just because a minority of requests truly need it.

A database should be stable, affordable, and quiet. It should store facts. It should not become the most expensive, most fragile, and most attention-hungry part of the system.

I have been using Prisma Next in a real agent product, not as a toy example and not as a benchmark. The product has users, teams, billing, approvals, scheduled tasks, webhooks, a public discovery surface, and an assistant that can help operate parts of the system. The data model has not stayed still.

That is where Prisma Next became interesting to me.

The main value I felt was not “a nicer ORM.” It was the contract-first shape: the data contract is the source of truth, and the rest of the system follows from it. Types, runtime access, migrations, and database verification all point back to one explicit place.

That sounds small until the product starts moving quickly.

The Problem Is Not Just Queries

Most database tooling discussions start with query ergonomics. Can I write a join cleanly? Are filters type-safe? Is the generated client pleasant to use?

Those things matter, but they are not the whole data-layer problem in a product that keeps changing.

The harder problems are usually less glamorous:

• Which data model is the current product model?
• Did the migration that production needs actually land?
• Are the generated types still describing the database we are connected to?
• Can another engineer, or an agent, continue this work without reverse-engineering every hidden assumption?

In a small app, these questions are manageable by memory. In a product with accounts, teams, access control, approvals, billing events, integrations, publication metadata, and assistant state, memory stops being enough.

The system needs a contract.

What Prisma Next Got Right

The strongest idea in Prisma Next is that the contract is not just a schema file sitting next to the real work. It is the work.

In my project, the contract lives as a TypeScript data contract. The runtime reads the emitted contract artifact and exposes a typed Postgres runtime for serverless execution. Migrations live alongside the contract, so the history of the data model is reviewable instead of implied.

The day-to-day loop is direct:

edit contract -> emit -> plan migration -> review -> migrate -> verify

That loop is not exciting, and that is the point. It is explicit. It gives both humans and agents a narrow path to follow.

When the product model changes, I do not want the data layer to be clever. I want it to be honest. I want to see the contract change, the migration plan, and the verification result.

A Real Product Shape Changes Under You

One lesson from building an agent product is that the nouns change.

Early systems often start with low-level implementation nouns: runs, triggers, steps, events. Those are useful, but they are not always the durable product model. As the product matures, the useful user-facing nouns become higher level: agents, inboxes, tasks, schedules, automations, activity.

That kind of shift is where data layers get messy. Old names stay in tables. New names appear in APIs. Some runtime concepts become product concepts by accident. A few JSON fields become load-bearing because nobody wants to stop and model them properly.

Prisma Next does not magically solve product modeling. No tool does. But contract-first development forces the conversation into the right place:

What is the product relationship now?

What deserves a model?

What should remain runtime state?

What needs a constraint, an index, or a migration?

That pressure is useful. It turns product drift into a concrete contract diff instead of a vague feeling that the codebase is getting harder to reason about.

Migrations Feel Better When They Are Reviewable

I care a lot about production changes being boring. For database work, boring means observable and recoverable.

The flow I ended up trusting was simple:

1. inspect the contract change
2. review the planned migration
3. apply it deliberately
4. verify the live database against the expected contract

The important part is not that there is a command for each step. The important part is that each step produces evidence.

If the generated types are stale, re-emit the contract. If the database does not match, verify catches drift. If a migration fails, the contract and migration state tell you where you are instead of leaving you to infer it from application errors.

That changes the emotional texture of database work. It is less “I hope this push did the right thing” and more “I can see what changed, what ran, and what the database currently claims to be.”

Why It Works Well With Agents

The most surprising part of the experience was how well this model fits agent-assisted development.

Agents are not weak because they cannot type code. They are weak when the environment is full of implicit state. If the only way to understand the data layer is to read a dozen files, remember a Slack thread, inspect production by hand, and guess which migration has run, the agent will eventually make something up.

Prisma Next reduces that guessing.

An agent can read the contract. It can inspect migrations. It can run emit, plan, migrate, and verify. It can connect the runtime types back to the contract artifact. The workflow has observable checkpoints.

That matters more than it first appears.

For a human, a contract-first flow is a discipline. For an agent, it is a rail. It narrows the possible next actions and makes failures easier to classify.

When something breaks, the question becomes concrete:

• Is the contract source wrong?
• Were the artifacts emitted?
• Was the migration planned?
• Did the migration apply?
• Does the database verify against the contract?

Those are much better questions than “why is the ORM acting weird?”

The smoothness comes from less guessing, not fewer commands.

Client-Owned Memory, Server-Owned Data

Another design lesson from the product was to keep memory and durable data separate.

The assistant has client-owned memory and session state. That belongs close to the user experience: preferences, facts, task context, and compressed conversation checkpoints. It should not silently become part of the database contract unless it is truly product data.

The server-side product model is different. Teams, permissions, billing, approvals, published templates, and operational state need durable structure. They need constraints. They need migration history. They need to be verified.

That separation made Prisma Next feel like the right tool for the durable side. It gives the product data a contract without pretending every piece of assistant context belongs in the same layer.

This is an important distinction for agent products. If everything becomes “memory,” the product loses structure. If everything becomes relational data, the assistant becomes heavy and unnatural. The contract helps draw the line.

Where There Is Still Friction

The experience was not frictionless.

Some parts still feel early. Project layout and scaffolding details matter more than they should. Production database connections can still fail in ways that require careful recovery. Migration tooling is only as good as the operational discipline around it.

But those are surface-area issues. They are real, but they do not undermine the core model.

The core model is strong: make the data contract explicit, derive the runtime from it, make migrations reviewable, and verify the database instead of assuming it is correct.

That is the part I would keep.

The Real Takeaway

Prisma Next is not automatically the lowest-cost choice for every project.

If you have three tables, a few raw SQL queries, and no meaningful schema evolution, a lighter setup may be better. I would not add contract machinery just to feel sophisticated.

But if your product model is evolving, and especially if agents are going to help maintain or operate the system, the tradeoff changes.

In that world, the best data layer is not just the one with the prettiest query API. It is the one that makes state explicit, migrations reviewable, and correctness verifiable.

That is what Prisma Next made clear to me.

Contract-first is not only a nicer way for humans to model data. It is also a better working surface for agents.

The first two Patchwork articles were about the model: stop editing .pub-cache, commit dependency patches as reviewable artifacts, and keep ownership boundaries clear.

This one is about proof.

Oxy, a policy-first HTTP client for Dart and Flutter, already uses Patchwork to carry a real dependency fix. The bug was not in Oxy’s own source. It lived in http_parser, a direct runtime dependency. But the behavior was visible through Oxy’s retry policy, so Oxy still owned the user-facing result.

That is exactly the kind of edge case Patchwork was built for.

The bug: Retry-After depends on HTTP-date parsing

HTTP retry behavior is not just exponential backoff. Servers can send Retry-After to say when a client should try again.

That header can be an integer number of seconds, or it can be an HTTP-date. Oxy’s RetryPolicy respects that header. If a response includes a valid Retry-After date, Oxy uses it instead of its normal backoff delay.

The parsing path is intentionally small: Oxy reads the header, tries seconds first, and then delegates HTTP-date parsing to package:http_parser.

That is the right dependency choice. Oxy should not carry its own full HTTP-date parser just to implement retry behavior.

But it also means a parser edge case can become an Oxy behavior bug.

The edge case: obsolete RFC850 dates

HTTP-date has historical formats. One of them is the obsolete RFC850 form, such as a weekday name, a two-digit year, and GMT.

The tricky part is the two-digit year.

The old implementation in http_parser treated that form as 1900 plus the two-digit value. That makes some modern dates land in the wrong century. For Retry-After, that can change whether a retry delay is in the future, in the past, or effectively zero.

The narrow fix is not dramatic. The parser should interpret the two-digit year relative to the current century, then roll it back by 100 years if the result is more than 50 years in the future. That is the RFC 9110 rule the Oxy patch follows.

Small fix. Real behavior. Wrong dependency layer.

The usual options are awkward

When a bug lives in a dependency, a package maintainer has a few familiar choices.

They can fork the dependency. That works, but now a small date-parsing fix becomes a long-lived package ownership problem. Every future dependency update has to account for the fork.

They can wait for upstream. That is the best long-term outcome, but it may not unblock the package release that needs correct behavior now.

They can use dependency_overrides locally. That can make tests pass on one machine, but it does not explain why the replacement exists, does not make the patch reviewable as a package artifact, and does not compose cleanly for downstream users.

Oxy needed a smaller boundary.

What Oxy committed

Oxy uses Patchwork’s package-provided patch workflow.

The important files are ordinary repository files:

• pubspec.yaml depends on http_parser and patchwork as runtime dependencies.
• patchwork.yaml declares that Oxy provides a patch for http_parser 4.1.2.
• patches/http_parser@4.1.2.patch contains the actual source diff.
• CHANGELOG.md records the fix under Oxy 0.6.0.
• policy tests verify the visible Retry-After behavior.

That shape matters.

The patch is not hidden in a cache. It is not buried in a fork. It is not an unexplained override. It is a reviewed file next to the package that needs the behavior.

The provider manifest is also explicit. It names http_parser, pins the source identity, points at the patch file, and records the reason: fixing RFC850 two-digit HTTP-date years used by Retry-After.

That is what makes the dependency patch auditable.

Why this is a provider overlay, not a root patch

This is not just an app carrying a local workaround.

Oxy is a published package. Its users depend on Oxy for HTTP client behavior. They should not have to copy an http_parser patch into every downstream application just to get correct retry behavior from Oxy.

At the same time, Oxy should not be allowed to silently patch anything in a downstream dependency graph. That would be too broad.

The boundary is direct runtime dependency ownership.

Oxy directly depends on http_parser. Oxy observes the Retry-After behavior. Oxy carries the regression tests. Oxy declares the provider overlay. Downstream applications receive the composed behavior without owning the workaround.

That is the difference between convenience and ownership.

The proof is in the tests

The strongest part of this case is not the patch file. It is the regression surface around it.

Oxy has tests for normal HTTP-date Retry-After values. It has tests for RFC850 dates in the current century. It has tests for the rollover case where the interpreted date would otherwise be more than 50 years in the future. It also has tests for invalid Retry-After values and obsolete dates that should resolve to zero delay.

Those tests make the patch measurable as Oxy behavior, not just dependency surgery.

That is an important promotion point for Patchwork: a dependency patch should not end at “the diff applies.” The package carrying the patch should prove the behavior it needs.

Patchwork supplies the artifact boundary. The package still owns the product behavior.

What this avoids

This Oxy fix avoided a fork of http_parser for one small parser edge case.

It avoided treating pubspec_overrides.yaml as durable truth.

It avoided asking every downstream application to understand an implementation detail of Oxy’s retry policy.

It avoided pretending the issue did not exist until upstream released a fix.

Instead, the repository now has a compact story:

• here is the dependency version;
• here is the reviewed patch;
• here is why the package provides it;
• here are the tests that prove the visible behavior;
• here is the changelog entry that tells users what changed.

That is the shape dependency patching should have.

The upstream path still matters

Patchwork does not make upstream irrelevant.

The best long-term outcome for this kind of fix is still upstream adoption. When the dependency releases a corrected version, Oxy can remove the provider overlay and the patch file in a normal dependency update.

That removal path is part of the point.

A good temporary patch should be easy to find, easy to review, and easy to delete when it is no longer needed.

That is harder when the fix lives in a fork. It is much harder when the fix lives in someone’s local pub cache.

The lesson

The value of Patchwork is not that it can modify dependency code. You can always modify dependency code if you are willing to make enough mess.

The value is that it gives dependency fixes a disciplined place to live.

In Oxy’s case, Patchwork let a Dart package ship correct Retry-After behavior without taking ownership of an http_parser fork. The fix stayed narrow. The reason stayed visible. The tests stayed in the package that owned the behavior. Downstream users did not have to manage the workaround themselves.

That is the real pitch:

Patchwork turns a dependency workaround into a reviewable package artifact.

You can find Patchwork on pub.dev at https://pub.dev/packages/patchwork and on GitHub at https://github.com/medz/patchwork.

The Oxy repository is at https://github.com/medz/oxy.

The first Patchwork article was about the obvious pain: editing .pub-cache is fast, but it is not a workflow. A dependency patch should be reviewable, committed, and reproducible.

That story mostly fits apps and workspaces. The root project needs a patched dependency while it runs, so the root project owns the patch file.

The second workflow is more subtle.

What happens when a published Dart package needs to carry a small fix for one of its own runtime dependencies? The downstream application should not have to copy your patch file. It should not need to understand your temporary workaround. It should depend on your package and run normally.

That is the problem package-provided patches are designed for.

The easy case: your app owns the patch

Root-project patches are easy to explain because the owner is obvious.

If an app needs patched behavior, the app carries the patch. It creates an editable copy of the resolved dependency, commits the edit as patches/<pkg>@<version>.patch, and regenerates local override wiring when needed.

That patch can target a direct dependency or a transitive dependency selected by the current pub resolution. The key point is not whether the package is listed directly in pubspec.yaml. The key point is that the root project is the runtime owner. It is the thing that needs the patched behavior.

For a root-owned patch, the durable file is simple:

patches/<pkg>@<version>.patch

The rest is activation state. .patchwork/ is an edit workspace. .dart_tool/patchwork/ is generated output. pubspec_overrides.yaml wires the patched copy into local resolution.

That is a good boundary for apps.

But package authors have a different problem.

The harder case: a package ships behavior downstream

Imagine you maintain a Dart package that depends on another package at runtime. There is a narrow bug in that dependency. You can reproduce it through your package. You can patch it locally. You may even have an upstream pull request open.

But your users do not depend on that lower-level package because they care about it. They depend on your package.

If every downstream app has to copy your patch file, your package has leaked implementation detail into every consumer project. If every downstream app has to add its own Patchwork dependency and register your workaround manually, the ownership boundary is wrong.

The package that needs the runtime fix should own the reviewed patch.

That is the purpose of package-provided patches: a published package can carry a reviewed patch for one of its direct runtime dependencies, and downstream applications can receive the composed behavior without copying the patch into their own repository.

Why direct runtime dependencies matter

Package-provided patches are intentionally narrower than root-project patches.

A root project can patch direct or transitive packages selected by its current pub resolution because the root project owns the whole runtime composition. It is allowed to say: this app needs this resolved package to behave differently.

A published package does not own the entire downstream application.

That is why package-provided patches should be limited to direct runtime dependencies of the providing package. Not dev dependencies. Not unrelated packages. Not arbitrary transitive packages several layers away.

This is not a technical inconvenience. It is the product boundary.

If a package could silently contribute patches for anything in the downstream graph, it would become hard to reason about who is responsible for a dependency change. Direct runtime dependency is the line where responsibility is still legible: the providing package depends on it, observes the behavior, reviews the patch, and declares why it is carrying the change.

Patch files need review before registration

A root-project patch is already reviewable, but a package-provided patch needs a stricter review habit.

The patch is no longer only a local application workaround. It can affect downstream applications that depend on your package. That means the patch file should be narrow, runtime-oriented, and intentional.

A package-provided patch should include the source files required for the runtime fix. It should not casually ship upstream tests, examples, documentation edits, formatting churn, or unrelated maintenance. Those changes may be useful for an upstream pull request, but they are not usually part of what downstream applications need to run.

That is why Patchwork treats overlay registration as a separate step. You do not create a package-provided patch merely by editing a dependency. You create the patch, review the file, and then register it.

A minimal shape looks like this:

dart pub add patchwork
dart pub get
dart run patchwork patch collection
# edit .patchwork/collection@<version>/
dart run patchwork commit collection
# review patches/collection@<version>.patch
dart run patchwork overlay add collection --reason "Fix parser behavior used by this package."

The files that belong in the published package are:

patchwork.yaml
patches/<pkg>@<version>.patch

That commit says two things: here is the patch artifact, and here is the provider manifest that declares when and why this package contributes it.

patchwork.yaml is not a second patch system

The provider manifest is easy to misunderstand.

patchwork.yaml is not the patch itself. It is not a lockfile. It is not a hidden source of truth competing with patches/<pkg>@<version>.patch.

The patch file remains the durable change. patchwork.yaml records the reviewed contribution: package name, version, source identity, patch path, and reason. Downstream hook logic can then inspect provider manifests, match them against the resolved dependency graph, and compose the generated output when the target package version and source identity match.

That design keeps the same principle as the root workflow: committed files describe intent, generated files can be recreated.

Downstream apps should stay boring

The point of package-provided patches is not to make downstream applications think about more machinery. It is the opposite.

A downstream app should depend on the providing package and run its normal workflow. It should not copy another package’s patch file. It should not register a workaround it does not own. It should not become responsible for reviewing a dependency change whose behavior is only observable through the package it consumes.

The provider owns the patch because the provider owns the runtime dependency relationship.

That ownership also gives the provider a clear removal path. When upstream releases the fix, the package can remove patchwork.yaml and the patch file in one ordinary package update. Consumers receive the cleanup through the same dependency update path they already use.

The social contract

Dependency patching can look suspicious if it is framed as a way to silently modify the ecosystem.

That is not the goal.

A package-provided patch should be a release unblock, a compatibility bridge, or a narrow behavior adjustment that stays visible in the providing package’s source. The patch should be reviewed. The reason should be written down. Upstream should still be the long-term home for the fix whenever possible.

Patchwork is useful because it makes that temporary state explicit instead of pretending it does not exist.

The real question is not “can this package patch that dependency?”

The better question is: who owns the behavior, who should review the change, and who should have to know it exists?

For root projects, the answer is usually the app or workspace.

For package-provided patches, the answer is narrower: the package that directly depends on the runtime dependency, carries the reviewed patch, and shields downstream applications from the workaround.

That boundary is what keeps dependency patching understandable.

Patchwork is available on pub.dev at https://pub.dev/packages/patchwork and on GitHub at https://github.com/medz/patchwork.

Every Dart developer has made the same compromise at least once.

A dependency has a small bug. The fix is obvious. Upstream may accept it, but not before your release. Forking the package feels too heavy. Editing .pub-cache works for five minutes, then disappears the moment someone else runs the project.

That gap is where Patchwork lives.

Patchwork is a patch manager for Dart pub dependencies. It does not ask you to fork every package you touch, and it does not treat your global pub cache as a workspace. Instead, it turns a dependency change into a normal project artifact: a versioned patch file that can be committed, reviewed, and reapplied wherever the project runs.

Dependency fixes deserve code review

Most dependency patching starts as a local survival tactic. You find the package in .pub-cache, make the change, run the app, and confirm the bug is gone. That is useful as a debugging move, but it is a poor engineering boundary.

A cache edit has no durable identity. It is not in the repository. It is not visible in pull requests. It does not run in CI. It does not tell the next developer why it exists. It may even disappear during a routine pub cache repair or SDK refresh.

A fork solves some of that, but it introduces a different cost. Now a small compatibility fix becomes a new upstream remote, new release discipline, and often a long-lived divergence from the package you actually wanted to depend on. For some changes, a fork is absolutely the right answer. For many release unblocks and narrow compatibility fixes, it is heavier than the problem.

The useful middle ground is simple: keep the change close to the project that needs it, but make it reviewable.

That is the core idea behind Patchwork.

The model

Patchwork separates four things that are often blurred together:

• pubspec.lock tells you which dependency version the project resolved.
• .pub-cache remains the original package source, not your editing workspace.
• .patchwork/<package>@<version>/ is a disposable edit directory.
• patches/<package>@<version>.patch is the durable artifact you commit.

The generated local wiring lives in pubspec_overrides.yaml and .dart_tool/patchwork/. Those files are activation state. They can be recreated from the committed patch file and the current pub resolution.

That split is important. Patchwork does not make pubspec_overrides.yaml the source of truth. The patch file is the source of truth. Overrides are how the patched dependency is activated locally.

A root-project patch

For an app or workspace that owns its dependency patch, the workflow is intentionally small:

dart pub add dev:patchwork
dart pub get
dart run patchwork doctor
dart run patchwork patch collection
# edit .patchwork/collection@<version>/
dart run patchwork commit collection
dart run patchwork apply collection

After commit, the file that matters is:

patches/collection@<version>.patch

That file is what belongs in version control. It can be reviewed like any other source change. A teammate or CI job can apply it without knowing which local cache directory you edited when you first found the fix.

Patchwork also supports root-owned patches for transitive packages selected by the current pub resolution. That matters in real projects because the bug you need to patch is not always one of the packages listed directly in your pubspec.yaml. The owner is still the root project: the app or workspace carries the patch because it is the thing that needs the patched behavior at runtime.

Package-provided patches

There is a second workflow for published packages that need to carry a patch for one of their direct runtime dependencies.

That case is deliberately stricter. A package-provided patch is not just a local project convenience; it can affect downstream applications. Before registering it, you should review the patch file and keep it narrow. Include runtime source files required for the fix. Do not publish upstream tests, examples, docs, or unrelated maintenance unless those files are actually needed at runtime.

In that workflow, the package commits both:

patchwork.yaml
patches/<pkg>@<version>.patch

Downstream applications should not have to copy that patch file or add their own Patchwork dependency just to consume the providing package. Patchwork’s package hook can discover the provider manifest and compose matching patches when the resolved dependency version and source identity match.

That is a more advanced feature, but the principle is the same: the reviewed patch file is the durable artifact, and generated output remains generated output.

What Patchwork is not

Patchwork is not a new package resolver. It is not a replacement for upstream contribution. It is not a reason to keep private patches forever.

The best ending for most dependency fixes is still upstream: open the issue, send the pull request, remove the local patch when a release lands.

Patchwork is for the part in between: the days or weeks where your project needs to move, the change is small enough to review locally, and the team needs a reproducible way to carry it.

It also avoids pretending that dependency_overrides are a complete workflow. Overrides are useful, but they are only wiring. They say where pub should point. They do not explain how the replacement source was produced, whether it still matches the resolved dependency version, or what should be committed.

A good patch workflow should make those boundaries explicit.

Why this matters for Dart

Dart projects already have a strong package ecosystem and a predictable pub workflow. That is exactly why dependency patching should feel boring.

When a patch is needed, the workflow should be ordinary:

• create an editable copy of the resolved dependency;
• make the smallest required change;
• commit a versioned patch file;
• apply it consistently in local development and CI;
• remove it when upstream catches up.

No mystery cache edits. No hidden machine state. No unexplained overrides.

That is the design goal for Patchwork: reviewable dependency patches for Dart pub packages, with the durable truth living in your repository.

You can find Patchwork on pub.dev at https://pub.dev/packages/patchwork and on GitHub at https://github.com/medz/patchwork.

From copied request snippets to a policy-first network layer: Oxy is not about sending one request, but maintaining many.

The hard part of a real network layer is rarely “how do I send one request?” It is “how do I keep many requests reliable over time?”

The first version of a network layer usually looks harmless.

Send a GET, parse some JSON, map it into a model. Send a POST, attach a token, handle an error. The code is short, the feedback loop is fast, and adding an abstraction can feel unnecessary.

The trouble usually starts around the twentieth request.

That is when a team begins to run into familiar problems that are easy to recognize and hard to keep consistent:

• Some requests have a timeout. Some do not.
• One call site throws on 404. Another returns null.
• Some requests retry. Some do not, and the reason only exists in someone’s memory.
• A file upload fails and gets retried, but the second attempt is using a stream that has already been consumed.
• Flutter Web and native transport differences start leaking into business code.
• API client tests require a local mock server, so many paths quietly go untested.
• Callers only know that “the network failed”, not whether the failure was a timeout, status error, decode error, cancellation, or policy rejection.

None of these problems is dramatic on its own. The real danger is that every call site starts answering the same set of network questions in a slightly different way.

Dart can already send HTTP requests. package:http does a good job of solving the problem of sending one request.

Oxy is focused on the next stage: when a Dart or Flutter project needs to maintain a set of API clients, how do you keep the network layer consistent, testable, and explainable?

Put differently: an HTTP call is easy. A reliable API client is hard.

Copy-Paste Is Not the Real Problem

Many projects start with code like this:

Future<Map<String, Object?>> getUser(String id) async {
  final response = await http
      .get(Uri.parse('$baseUrl/users/$id'), headers: authHeaders())
      .timeout(const Duration(seconds: 10));  if (response.statusCode == 401) {
    throw AuthExpired();
  }

  if (response.statusCode < 200 || response.statusCode >= 300) {
    throw ApiException(response.statusCode, response.body);
  }

  return jsonDecode(response.body) as Map<String, Object?>;
}

There is nothing wrong with this function.

The problem is that it gets copied into getPosts, createOrder, uploadAvatar, background sync jobs, and temporary methods inside Flutter screens. Each copy brings along a hidden network contract:

• How is the URL resolved?
• Who adds auth headers?
• Is timeout a shared policy or a local habit?
• When does a status code become an error?
• What is safe to retry?
• Can the response body be read again?
• Does the error object carry enough context for callers and logs?

If those answers are scattered across dozens of functions, you no longer have an API client that can be reviewed as a module. You have many similar request snippets with subtly different behavior.

One HTTP call is simple. Once auth, timeout, status handling, and retry logic are copied across many requests, the network layer becomes difficult to reason about.

Oxy is not trying to save a few lines of code.

Saving a few lines is not the core value of a network layer. The real value is moving repeated decisions out of call sites and into policies that a client can declare, test, and review.

Business Code Should Read Like Business Code

A maintainable API client should let endpoint methods stay close to the domain:

class UsersApi {
  UsersApi(this._client);

  final Client _client;
  Future<Map<String, Object?>> getUser(String id) async {
    final response = await _client.get('/users/$id');
    return await response.json<Map<String, Object?>>();
  }
}

There is no token handling, timeout logic, retry loop, redirect handling, or status validation in that method.

That is not because those concerns disappeared. It is because they should not be reimplemented inside every endpoint method. UsersApi.getUser should describe how to call the user endpoint, not rebuild network governance on the side.

In Oxy, those defaults live in ClientOptions:

import 'package:oxy/oxy.dart';

final client = Client(
  ClientOptions(
    baseUrl: Uri.parse('https://api.example.com'),
    timeoutPolicy: const TimeoutPolicy(total: Duration(seconds: 10)),
    retryPolicy: const RetryPolicy(maxRetries: 2),
    statusPolicy: StatusPolicy.throwOnError,
    middleware: [
      RequestIdMiddleware(),
      AuthMiddleware.staticToken('your-token'),
    ],
  ),
);

final users = UsersApi(client);

This is not just “centralized configuration.” It gives code review a real boundary:

• Endpoint methods own path, query, payload, and decoding.
• Client policies own timeout, retry, redirect, and status validation.
• Middleware owns cross-cutting behavior such as auth, request IDs, cookies, and logging.
• Transport owns the actual send operation and can be swapped in tests.

When the boundary is clear, many bugs can be questioned during design instead of being reconstructed from logs after production.

Policy-first is not about adding a configuration object. It is about moving network rules out of scattered call sites and into an explainable control plane.

Policy-First Does Not Mean More Configuration

policy-first can sound abstract. It does not mean every behavior should become a configuration knob, and it does not mean the network layer should become a framework.

It starts with a more practical observation: real API clients have rules that should exist before any individual request is written.

For example:

• What is the total timeout?
• Should connect, send, first byte, and read timeouts be handled separately?
• Which status codes are retryable?
• Should retry be limited to idempotent methods?
• Should redirects be followed automatically?
• Should non-2xx responses throw by default or return a response?

If these rules are written locally inside request functions, they are hard to test consistently and hard for a team to remember.

Oxy makes them explicit policies:

final client = Client(
  ClientOptions(
    timeoutPolicy: const TimeoutPolicy(
      total: Duration(seconds: 20),
      firstByte: Duration(seconds: 5),
    ),
    retryPolicy: const RetryPolicy(
      maxRetries: 2,
      retryableStatusCodes: {408, 429, 500, 502, 503, 504},
    ),
    redirectPolicy: RedirectPolicy.follow,
    statusPolicy: StatusPolicy.throwOnError,
  ),
);

That changes the network layer from “control flow scattered across many functions” into “a default behavior table you can actually read.”

At this point, a useful question for any project is: where do these rules live today? If the answer is “everywhere”, API client quality is already starting to drift.

Middleware Needs to Know Its Timescale

Middleware is one of the easiest places for a network layer to become a junk drawer.

Adding a token can be middleware. Logging can be middleware. Cookie handling can be middleware. The issue is that these behaviors do not all live on the same timescale.

Some behavior should run once for the user’s logical request:

• Generate a request ID.
• Add an auth header.
• Attach tenant, trace, locale, or other business context.

Other behavior should run for every actual network attempt:

• Record a new attempt after a retry.
• Merge cookies through a cookie jar.
• Log transport-level activity.
• Read attempt-level response information.

If those two categories are mixed together, retry makes the behavior ambiguous. Does this middleware run once, or once per attempt?

Oxy separates the two:

final client = Client(
  ClientOptions(
    baseUrl: Uri.parse('https://api.example.com'),
    middleware: [
      RequestIdMiddleware(),
      AuthMiddleware.staticToken('your-token'),
    ],
    networkMiddleware: [
      CookieMiddleware(MemoryCookieJar()),
      LoggingMiddleware(),
    ],
  ),
);

middleware targets the logical request.

networkMiddleware targets the network attempt.

The distinction is easy to miss in a demo, but it matters in production. It keeps retry, logging, cookies, auth, and request IDs from becoming tangled in ways that no one can explain.

Retry Is Not a For Loop

Many retry bugs begin with the idea that retry simply means “try again after failure.”

for (var attempt = 0; attempt < 3; attempt++) {
  try {
    return await sendRequest();
  } catch (_) {
    await Future<void>.delayed(backoff(attempt));
  }
}

This looks reasonable until you hit request bodies.

JSON, bytes, and form data are usually replayable. A one-shot stream is not. For example, a stream opened for a file upload may have been consumed by the first send. Retrying it does not make the request more reliable. It creates a more subtle failure.

Oxy’s Body carries replayability metadata. Retry policy does not look only at error type and status code. It also checks whether the request can be safely replayed.

A retry policy cannot only look at error type. It needs to understand method, status, timeout, and body replayability.

This is where policy-first becomes valuable: a policy is not just a configuration value. It needs to understand the structure of the request.

A reliable retry strategy needs to answer at least these questions:

• Is this method allowed to retry?
• Is this error actually worth retrying?
• Did the server send Retry-After?
• Can the body be replayed?
• If retry is exhausted, can the caller inspect the last error or response?

If these questions are scattered through business code, it is hard to know whether every endpoint answered them correctly.

Status Codes Should Not Become a Religious Debate

One long-running network library debate is whether non-2xx responses should throw or return a response.

Treating that as a global philosophy question is not very useful. The real answer usually depends on endpoint semantics.

For most API clients, it is reasonable for 500, 401, 403, and 422 responses to enter a typed error path. Callers should not have to write this everywhere:

if (response.status >= 400) {
  // ...
}

But some endpoints use 404 as normal control flow. For example: “user does not exist, return null."

Oxy throws StatusError for non-2xx responses by default, and lets a request opt out locally:

Future<Map<String, Object?>?> findUser(String id) async {
  final response = await client.get(
    '/users/$id',
    options: const RequestOptions(
      statusPolicy: StatusPolicy.returnResponse,
    ),
  );

  if (response.status == 404) {
    return null;
  }

  return await response.json<Map<String, Object?>>();
}

This is more practical than arguing whether HTTP errors should always throw or always return.

Defaults serve the common case. Local policy expresses the exception. A reader can immediately see that this endpoint did not forget to handle 404. It intentionally treats 404 as a business branch.

No-Throw Flow Should Not Duplicate Every Method

Many network layers grow two parallel method sets:

• get
• safeGet
• post
• safePost
• put
• safePut

That feels clear at first, but it turns into a method matrix over time. Every new HTTP method or parameter has to be considered twice.

Oxy keeps no-throw flow behind Result:

final result = await client.requestResult('GET', '/health');

result.fold(
  onSuccess: (response) {
    print(response.status);
  },
  onFailure: (error, trace) {
    print(error);
  },
);

If you already have a Request, you can use client.sendResult(...). For one-off requests, there is also top-level fetchResult(...).

The important part is not the name Result. It is avoiding a parallel API surface. Throwing and no-throw flows should share the same request model, policies, middleware, and transport instead of evolving separately.

Testing Should Not Require a Server

The test experience of an API client determines whether it actually gets tested.

If testing an endpoint wrapper requires starting a local server, managing ports, and handling lifecycle cleanup, many teams will only test the happy path, or skip the test entirely. Not because they do not care about tests, but because the friction is too high.

Oxy includes MockTransport, so tests can stop at the API client boundary:

import 'package:oxy/oxy.dart';
import 'package:oxy/testing.dart';

final transport = MockTransport((request, context) async {
  if (request.uri.path == '/users/42') {
    return Response.json({'id': '42', 'name': 'Ada'});
  }
  return Response.json({'error': 'not found'}, status: 404);
});
final client = Client(
  ClientOptions(
    baseUrl: Uri.parse('https://api.example.com'),
    transport: transport,
  ),
);
final users = UsersApi(client);
final user = await users.getUser('42');
print(user['name']); // Ada

That kind of test can verify what actually matters:

• Did the endpoint request the correct path?
• Were query, headers, and body built correctly?
• Did 404, 500, and timeout paths behave as expected?
• Did middleware participate in the request?
• Did retry actually happen, and how many times?
• Was a non-replayable body prevented from retrying?

None of that requires a real HTTP server.

More importantly, the test is no longer only proving that a server can return data. It is proving that the API client contract is stable.

Oxy Is Not Trying to Replace Every HTTP Client

If you are writing a small script that sends two requests, package:http is more direct.

If your project is already deeply built around Dio’s ecosystem, interceptor model, upload/download features, and conventions, there is no reason to migrate just for novelty.

Oxy is a better fit when:

• You are building a Dart or Flutter SDK.
• You maintain a set of app-specific API clients.
• You want native and Web to share the same public API.
• You want retry, timeout, redirect, and status validation to have explicit defaults.
• You want errors to be typed models rather than scattered exceptions and strings.
• You want deterministic API client tests without a real server.
• You do not want the network layer split across multiple adapter packages.

That is the position Oxy should be understood in today: not a feature-heavy HTTP client, but a small core for Dart and Flutter API clients.

Its public types intentionally avoid branded names:

• Client
• Request
• Response
• Headers
• Body
• Policy
• Middleware
• Context

The goal is for the network layer to look like the shape it naturally needs, not like a new world invented by a library.

Trust Is the Hardest Part of a Foundation Library

An HTTP client sits at the bottom of business flows. If it fails, it can affect login, payments, sync, uploads, background jobs, and the stability of the entire app.

That is why choosing a library like this is rarely only about whether the API feels nice. The real questions are:

• Is the direction clear?
• Does the library know what it is not trying to solve?
• Are error boundaries explainable?
• Is the test model lightweight enough?
• Will the core abstractions change names again in the next release?

After Oxy 0.3.0, the focus is narrower: a policy-first HTTP client for Dart and Flutter API clients.

That means the most valuable work is not piling on more features. It is making the core more trustworthy:

• Better cookbooks.
• More realistic SDK and API client examples.
• Clearer Web/native behavior documentation.
• More edge-case tests.
• A clearer migration and stability story.

Developers will not trust an HTTP client because of one article. The best an article can do is make the problem concrete, show the design tradeoffs, and let readers decide whether the library is solving a problem they actually have.

That is what this article is trying to do.

A Checklist You Can Take Away

Even if you never use Oxy, these questions are useful for reviewing your own Dart or Flutter network layer:

• Does every endpoint follow a timeout policy, or does each function improvise?
• Is non-2xx handling consistent?
• Does retry understand method, status, error type, and body replayability?
• Do auth, request ID, cookie, and logging middleware run at the logical request level or the network attempt level?
• Can callers distinguish timeout, status, decode, cancellation, and network failures?
• Do API client tests require starting a server?
• Are Web/native differences hidden behind a transport boundary?
• Is business code still repeating network governance?

If you can answer these clearly, your network layer already has a strong foundation.

If the answer is often “it depends on the function”, you may not need another helper. You may need a more stable API client path.

Closing

HTTP requests are easy.

The hard part is making the twentieth, fiftieth, and hundredth request keep the same timeout, retry, status policy, middleware behavior, and test model.

Oxy is not trying to answer “how do I send a request?” It is trying to answer “how do I keep a set of Dart and Flutter API clients maintainable over time?”

If you are cleaning up a Dart or Flutter network layer, or building an SDK, you can take a look at Oxy:

• pub.dev: https://pub.dev/packages/oxy
• GitHub: https://github.com/medz/oxy

I would also like to know: what is the most painful part of your Dart or Flutter network layer today? Retry, testing, Web/native differences, error modeling, or long-term API client maintenance?

In the world of Flutter development, state management is like that thorny bramble — it should be simple, yet it always drags you into a swamp of boilerplate code. Provider? Too many listeners. Bloc? Events feel like playing Tetris. Riverpod? Elegant, but you still have to learn a bunch of new concepts. Have you ever wondered if state management could “magically” inject into your Widgets like Vue.js, with just one line of code automatically responding to changes?

Hi, I’m Seven, a Flutter-obsessed developer. Today, I want to take you into Oref — a reactive state management library based on signals. It’s not just another “framework,” but a lightweight “magic wand” that frees you from the chains of StatefulWidget, letting you focus on writing clean, fast code. It’s 2025 — time to upgrade your toolkit.

The Pain Points of State Management: Why Are We Always Struggling in “Refactoring Hell”?

Recall: You just finished a counter Widget, but adding an async API call forces you to refactor into StatefulWidget, add setState, and listen for changes everywhere. Or with Provider, you have to wrap layers of Consumer, making the code bloat like Russian nesting dolls. The result? Performance bottlenecks, debugging nightmares, and endless “why not refactor?” meetings.

The Flutter community has tried various solutions: from the primitive setState era, to BLoC’s event-driven approach, to Riverpod’s dependency injection. But the core issue remains: too much boilerplate code, and reactivity that’s too passive. Oref is here, disrupting it all with a “signals” pattern — inspired by Solid.js and Vue’s reactivity system, but tailored specifically for Flutter.

What is Oref? A Zero-Boilerplate, Ultra-High-Performance Signals Library

Oref is built on alien_signals, providing signals, computed values, and effects. Its killer feature? Context injection: Signals “magically” bind directly to BuildContext without hooks or mixins. Your StatelessWidget instantly becomes a reactive powerhouse.

• Core Philosophy: Non-intrusive. Oref doesn’t force you to rewrite existing code; it integrates like air.
• Performance Champion: With optimizations from alien_signals, Oref excels in rebuild and response speeds, especially for high-frequency updates. Early user feedback shows it significantly reduces memory usage and rebuild overhead in real apps.
• Async-Friendly: Built-in useAsyncData supports Future/Stream, seamlessly handling loading states.

Installation is super simple:

flutter pub add oref

Hands-On Example: From Zero to Hero in Just 10 Lines of Code

Let’s demonstrate with a classic counter. A traditional Provider version might take 50+ lines; Oref? Check this out:

import 'package:flutter/material.dart';
import 'package:oref/oref.dart';

void main() => runApp(MyApp());

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final count = signal(context, 0); // Create a sugnals
    final increment = () => count(count() + 1); // increment count

    return MaterialApp(
      home: Scaffold(
        body: Center(
          child: Text('Count: ${count()}'), // read the count value
        ),
        floatingActionButton: FloatingActionButton(
          onPressed: increment,
          child: Icon(Icons.add),
        ),
      ),
    );
  }
}

Run it, tap the button — the count updates automatically, no setState or Consumer needed!

Magic, right? Signals batch changes in the background, rebuilding only what’s necessary. Want full examples? GitHub example folder is ready for you to fork.

Oref isn’t meant to replace everything — it’s complementary to flutter_hooks. If you love template-style, try flutter_signals; but if you crave minimalism, Oref is your new favorite.

Future Outlook: Oref’s Signals Will Illuminate Flutter

Flutter’s future is reactive — Oref is just the starting point. Try it out, and share your “magic moments” in the comments. Who knows, your App might be the next App Store star.

Like, share, subscribe — let’s make state management fun together!

What is Spry？

Spry is an HTTP middleware framework for Dart to make web applications and APIs more enjoyable to write.

How is it different from Shelf?

1. Middleware — Shelf middleware requires a complete call process (this is the source of my pain), and Spry absorbs the experience of Express/Koa, passing the “next” method to let the middleware decide when to call the next middleware.
2. Context — The Shelf context is attached to the request object and Spry wraps the request/response and whatever else with the context.
3. Request — Spry has made some practical packages for requests, which can facilitate the expansion of middleware, but it is not very different from Shelf. The only difference is that Spry’s request is in read-only mode. Middleware can be modified by context attachment.
4. Response — Shelf’s response is a read-only object. To modify it in the pipeline (such as middleware), you can only recreate the Response. Spry is different, the Spry response is created with the context and can be modified fluently.
5. Handlers — Shelf’s handler only accepts a request object, and then decides what type of Response to return. Spry accepts a context object, which contains the processing results of the pre-middleware, and also wraps the request and response. You can Modify the response anywhere until it is sent.

Middleware

A shelf middleware:

FutureOr<Response> middleware(Handler handler) {
  return (Request request) {
    // Front TODO
    
    final response = handler(request);

    // Rear TODO

    // Must return a response
    return response.
  }
}

The Spry middleware:

middleware(Context context, MiddlewareNext next) async {
  // Front TODO ...
  await next();
  // Rear TODO ...
})

Everyone will feel different about which is better, but Spry simplifies the return process of middleware and the complexity of function implementation.

Request handler

Spry define a handler:

handler(Context context) {
  // TODO
}

Shelf handler:

FutureOr<Response> handler(Request request) {
  // TODO
  return Response.ok(...);
}

You can see the difference, Spry does not force the processing to create a response, because the response already exists when the context is created. There can be no logic in the handler.

Router

Let’s take `/hello/{name}` as an example, in Shelf:

router.get('/hello/<name>', handler);

In Spry:

router.get('/hello/:name', handler);

There is no difference in this basic route matching except the syntax is different, but Spry supports more advanced route matching modes.

Now we come to a complex route:

// Spry
router.get('/hello/:name*', handler);

// Shelf
router.get('/hello/<name|.*>', handler);

The route matching mode of Spry router is similar to that of Express/Koa. Thanks to the practice of the NodeJS ecosystem for many years, we believe that path to regular expression is a very mature way with the least burden on developers.

Router mount / Subroute

The Spry sub-route mount is fully adaptive. We are not allowed to modify the path of the request object to simulate this process. The full path should be returned to the developer!

The shelf sub-routing completes the matching by modifying request.uri.path, and Spry determines the prefix at the routing stage to complete it!

Example:

// Spry
router.mount(prefix: '/hello', (Context context) {
  // TODO.
});

// Shelf
router.mount('/hello', (Request request) {
  // TODO

  return response;
})

In the above example, both sides are easy to use, what if we add path rules to prefix?

// Spry
router.mount(prefix: '/hello/:name', (Context context) {
  // TODO.
})

// Shelf
// not support

Here’s another example:

// Spry
final Router api = Router('/api')

api.get('/users/:id', handler); // full path is "/api/users/:id"

router.mount(api);

// Shelf
final Router api = Router();

api.get('/users/:id', handler); // full path is /users/:id

router.mount('/api', router); first match `/api/*`

In this example, route grouping is carried out by mounting sub-routes, which is not supported by shelf.

More…

If you think spry is ok. Lightly give spry a 🌟star.

GitHub: https://github.com/odroe/spry

A set of free MIT-licensed high-quality SVG icons for Vue.js development.

Install

• npm i @bytegem/vue-heroicons -S
• yarn add @bytegem/vue-heroicons

Using

import Vue from 'vue';
import Heroicons from '@bytegem/vue-heroicons';

Vue.use(Heroicons)

Example

<HeroIconAdjustmentsOutline />

Or

<hero-icon-adjustments-outline />

GitGub: https://github.com/bytegem/vue-heroicons

Docs website: https://bytegem.github.io/vue-heroicons/

ThinkSNS+ is the use of Laravel framework to achieve the user ecosystem, Can be friendly and low coupling development development applications.