next-rust-cache 0.1.11

Pluggable cache abstraction for Next Rust: in-memory and filesystem stores, tags, revalidation.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
<p align="center">
  <img src="https://raw.githubusercontent.com/iplustsolution/next-rust/main/website/public/logo.svg" alt="Next Rust logo" width="160" height="160">
</p>

<h1 align="center">Next Rust</h1>

<p align="center">
  Folders become routes. Rust becomes HTML. One binary goes to production.
</p>

```text
app/
├── layout.rs            the frame around every page
├── page.rs              /
├── about/page.rs        /about
└── blog/[slug]/page.rs  /blog/anything
```

```rust
// app/page.rs
use next_rust::prelude::*;

pub fn Page() -> impl View {
    div![
        h1!["Hello World"],
        p!["Welcome to Next Rust."]
    ]
}
```

That file is the whole route. There's no router to register it with and no
config to update. Save it, and `next-rust dev` serves it at `/`.

> **Early days.** Next Rust is pre-1.0 (0.0.x releases). It works: the
> examples run, the tests pass, and a fresh project builds into a single
> deployable binary. But APIs will still move before 1.0, and some pieces are
> missing. The honest list is the "Status & roadmap" page of the
> [documentation]#documentation. If something you need is on it, that's a
> great place to start contributing.

## The idea

If you've built a site with a file-based JavaScript framework, you already
know how this feels. You create a folder, drop in a page, wrap things in
layouts, and put an API handler next to the pages that use it.

We wanted that workflow without leaving Rust. So there's no Node.js, no
bundler, and no React. A build script reads your `app/` folder and generates
ordinary Rust code that wires everything together. The compiler checks all of
it, so a page that asks for data the framework can't give it doesn't build.
You find out at your desk instead of in production.

What comes out the other end is a single native server binary.

## A slightly bigger taste

A blog post that's pre-rendered at build time and refreshed every hour:

```rust
// app/blog/[slug]/page.rs
use next_rust::prelude::*;

pub const REVALIDATE: u64 = 3600;

pub async fn generate_params() -> Vec<Params> {
    posts::all().await.iter().map(|p| Params::new().with("slug", p.slug.as_str())).collect()
}

pub async fn Page(params: Params) -> Result<impl View> {
    let post = posts::find(params.get("slug").unwrap_or_default()).await.or_not_found()?;
    Ok(article![h1![post.title], p![post.summary]])
}
```

An API endpoint living right next to it:

```rust
// app/api/posts/route.rs
use next_rust::prelude::*;

pub async fn GET() -> Response {
    Response::json(&posts::all().await)
}
```

And a form that works with JavaScript turned off, then gets smoother when it's on:

```rust
#[server_action]
pub async fn subscribe(input: Signup) -> Result<()> {
    if !input.email.contains('@') {
        return Err(Error::validation([("email", "That doesn't look like an email")]));
    }
    newsletter::add(&input.email).await?;
    Err(redirect("/thanks"))
}

pub fn Page(form: FormState) -> impl View {
    form![
        action!(subscribe),
        input![name("email"), value(form.value("email"))],
        small![form.error("email").unwrap_or_default().to_owned()],
        button!["Subscribe"],
    ]
}
```

## Getting started

### 1. Install Rust (skip this if you already have it)

Next Rust needs **Rust 1.89 or newer**. To check what you have:

```sh
rustc --version
```

If that prints "command not found", or a version older than 1.89, install
Rust with [rustup](https://rustup.rs), the official installer.

**macOS and Linux:**

```sh
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

**Windows:** download and run
[rustup-init.exe](https://win.rustup.rs/x86_64). If it asks, also install
the Visual Studio C++ Build Tools.

Then open a **new** terminal and confirm:

```sh
rustc --version
cargo --version
```

If you had an older Rust already, update it with `rustup update stable`.

### 2. Install the Next Rust CLI

```sh
cargo install next-rust-cli
```

This installs the `next-rust` command from crates.io, and takes a minute or
two the first time. To use the newest code from `main` instead, install from
GitHub:

```sh
cargo install --git https://github.com/iplustsolution/next-rust next-rust-cli
```

Check it worked:

```sh
next-rust --version
```

If your terminal can't find `next-rust`, make sure `~/.cargo/bin` (on Windows,
`%USERPROFILE%\.cargo\bin`) is on your `PATH`, then open a new terminal.

### 3. Create a project

```sh
next-rust new my-app
cd my-app
```

New projects use the Next Rust version published on crates.io. Pass `--git`
to track the GitHub repository instead.

Adding Next Rust to an existing Cargo project instead? `cargo add next-rust`
and `cargo add --build next-rust-build`, then see
"Installation → Adding to an existing Cargo project" in the
[documentation](#documentation).

### 4. Run it

```sh
next-rust dev
```

Open http://localhost:3000 and edit `app/page.rs`. The browser reloads when
the build finishes. If you save something broken, the last good version keeps
running and the compiler error shows up in the page.

The first build downloads and compiles the framework, so give it a moment.
After that, rebuilds are fast.

When you're ready to ship:

```sh
next-rust build   # one small, self-contained binary in .next-rust/
next-rust start
```

## Styling with Tailwind CSS

Tailwind CSS is built in. Write Tailwind classes in your views and the CSS is
generated for exactly the classes you use. There's nothing to install and no
CSS file to write: no Node.js, no npm, no `tailwind.config.js`.

```rust
pub fn Page() -> impl View {
    main![
        class("mx-auto max-w-2xl px-6 py-24"),
        h1![class("text-4xl font-bold tracking-tight dark:text-white"), "Hello"],
        a![class("btn mt-8"), href("/docs"), "Read the docs"],
    ]
}
```

New projects use it from the start (`next-rust new my-app --no-tailwind`
if you'd rather write plain CSS). In an existing project, turn it on in
`next-rust.toml`:

```toml
[tailwind]
enabled = true
dark_mode = "media"                        # or "class" / "attribute"
plugins = ["@tailwindcss/typography"]      # optional official plugins

[tailwind.theme]                           # your design tokens
color-brand = "#f26b2a"                    # → bg-brand, text-brand, ring-brand/50, …
font-display = "Inter, sans-serif"         # → font-display

[tailwind.utilities]                       # your own classes
btn = "inline-flex rounded-lg bg-brand px-4 py-2 font-semibold text-white hover:bg-brand/90"
```

How it works:

- The engine is the **official Tailwind CSS v4.3.3**, so every class and
  variant in the [Tailwind docs]https://tailwindcss.com/docs works.
- The first time a Tailwind project builds, `next-rust dev` / `next-rust build`
  download Tailwind's standalone engine for your system (with a progress bar),
  check it against the published SHA-256 checksum, and cache it for every
  project on the machine. It needs `curl`, which macOS, Windows 10+ and most
  Linux systems already have.
- Only the classes found in `app/` and `src/` are generated. Development
  builds get readable CSS, release builds get it minified, and it's compiled
  into the binary, so servers need nothing extra.
- Release builds rename every class to a short random name, in the CSS and in
  the HTML (`mt-4 rounded-xl border` → `dx ce g`), with new names on every
  build. Development keeps the names you wrote. Turn it off with
  `minify_classes = false`, or keep single classes with `keep_classes`.
- Offline or locked-down CI? Download the executable yourself from the
  [v4.3.3 release]https://github.com/tailwindlabs/tailwindcss/releases/tag/v4.3.3
  and set `NEXT_RUST_TAILWIND_BIN=/path/to/tailwindcss`.

Everything else (custom variants, safelisting classes built at runtime, raw
keyframes) is on the Tailwind CSS page of the [documentation](#documentation).

## Deploying

`next-rust build` produces a single file, `.next-rust/my-app`, that contains
your whole app: server, pages, `next-rust.toml` and everything in `public/`.
There are two common ways to ship it.

### Copy the binary to a server

```sh
next-rust build
scp .next-rust/my-app you@your-server:/srv/my-app
ssh you@your-server 'PORT=8080 /srv/my-app'
```

Nothing else needs to be installed on the server. Build on the same operating
system and CPU architecture as the server (for example, a Linux x86-64 binary
for a Linux x86-64 server). If you develop on a Mac and deploy to Linux, use
Docker below: it builds the Linux binary for you.

### Run it with Docker

You need [Docker](https://docs.docker.com/get-docker/) installed and running.
All commands run inside your project folder.

**1. Create the Dockerfile**

```sh
next-rust docker
```

This writes two files:

- `Dockerfile` builds your app in the official Rust image, then copies only
  the finished binary into a minimal image
  (`gcr.io/distroless/cc-debian12:nonroot`) that runs as a non-root user.
- `.dockerignore` keeps `target/`, `.next-rust/`, `.git` and local `.env`
  files out of the build.

If a `Dockerfile` already exists, the command stops instead of overwriting it.
Use `next-rust docker --force` to replace it.

**2. Build the image**

```sh
docker build -t my-app .
```

The first build downloads and compiles every dependency, so it takes a few
minutes. Later builds reuse the Cargo cache and are much faster.

**3. Run the container**

```sh
docker run -p 3000:3000 my-app
```

Open http://localhost:3000. Press Ctrl+C to stop it; the server finishes the
requests it's handling before it exits.

**Everyday commands**

| What you want | Command |
|---|---|
| Run in the background and restart after crashes or reboots | `docker run -d --name my-app --restart unless-stopped -p 3000:3000 my-app` |
| See the logs | `docker logs -f my-app` |
| Stop it | `docker stop my-app` |
| Remove the stopped container | `docker rm my-app` |
| Use another port | `docker run -p 8080:8080 -e PORT=8080 my-app` |
| Pass secrets and settings | `docker run -p 3000:3000 -e DATABASE_URL=... -e API_KEY=... my-app` |
| Pass them from a file | `docker run -p 3000:3000 --env-file .env.production my-app` |

**Good to know**

- **Rebuild after every change.** Your pages, config and `public/` files are
  compiled into the image. After editing code, run `docker build` again, then
  replace the running container.
- **`.env` files are not in the image.** Pass secrets with `-e` or
  `--env-file` when you start the container, never bake them into the image.
- **Quiet by default.** A server running in the background prints only errors.
  Run with `docker run -it ...` to see the Next Rust startup screen.
- **`-p host:container`.** The left port is the one you open in the browser;
  the right one must match `PORT` inside the container (3000 unless you change
  it).
- **Small images.** The image holds one size-optimized binary (about 1–2 MB
  for a typical app) on top of the minimal base image. There is no Rust
  toolchain, shell or package manager in it.
- **Already have a Dockerfile from an older version?** Run
  `next-rust docker --force` to get the current one.

More options (Kubernetes, reverse proxies, TLS, platforms like Fly.io and
Railway) are on the Deployment page of the [documentation](#documentation).

## Staying up to date

New projects follow this GitHub repository, so updating is one command. Run
it inside your project:

```sh
next-rust upgrade
```

That does two things:

- moves your project's framework to the latest commit on GitHub (the exact
  version stays pinned in `Cargo.lock` until you upgrade again);
- reinstalls the `next-rust` command from GitHub.

To update just one of them:

```sh
next-rust upgrade --project   # only this project's framework
next-rust upgrade --cli       # only the next-rust command
```

You don't need to remember to check. Once a day, `next-rust dev` and
`next-rust new` quietly ask GitHub whether something newer exists, and print a
short note if it does. Nothing is installed without you running
`next-rust upgrade`, so an update never lands in the middle of your work. The
check sends no information about you or your project. Turn it off with
`NEXT_RUST_NO_UPDATE_CHECK=1`.

Prefer plain Cargo? `cargo update -p next-rust -p next-rust-build` updates the
project, and running the install command from step 2 again with `--force`
updates the CLI.

### Working on the framework itself

If you want to change Next Rust while building an app with it, point the app
at your own clone instead:

```sh
git clone https://github.com/iplustsolution/next-rust
cargo install --path next-rust/crates/next-rust-cli
next-rust new my-app --framework-path ./next-rust
```

That project uses your local copy, so `git pull` in the clone updates it.

## What's in the box

You don't have to learn all of this on day one, but it's there when you need
it:

- **Routing:** nested layouts, route groups like `(marketing)`, dynamic and
  catch-all segments, parallel `@slots`, intercepting routes, and plain
  `page.html` files for the pages you don't want to rewrite.
- **Rendering:** server-side rendering, static generation, timed and
  on-demand revalidation, and streaming with `loading.rs`. Next Rust works
  out which pages can be static, and `next-rust routes` tells you why the
  others aren't.
- **Backend:** API routes, middleware at any level of the tree, cookies,
  sessions, CORS, rate limiting, server-sent events and WebSockets.
- **Frontend:** HTML is escaped unless you explicitly ask for raw output.
  Tailwind CSS v4 is built in (no Node.js), and CSS modules are scoped at
  compile time. Pages ship zero JavaScript unless
  they use client navigation or an interactive island, and even then it's a
  single ~4 KB script. Navigating between pages that share layouts renders
  and sends only the part below them; the layouts stay on screen.
- **Tooling:** `new`, `dev`, `build`, `start`, `routes`, `check`, `doctor`,
  `generate` and `docker`.

Each of the 13 projects in [`examples/`](examples) comes with its own tests.
They're the quickest way to see how the pieces fit.

## How the repository is laid out

```text
crates/
├── next-rust          what applications depend on
├── next-rust-cli      the `next-rust` command
├── next-rust-build    turns app/ into generated Rust (runs in build.rs)
├── next-rust-router   scanning, validation, route matching
├── next-rust-view     the HTML macros and the streaming renderer
├── next-rust-ui       ready-made components (buttons, fields, select, date picker, …)
├── next-rust-icons    every Lucide icon
├── next-rust-server   HTTP, middleware, rendering pipeline, caching, actions
├── next-rust-macros   #[client], #[server_action], css_module!, asset!
├── next-rust-cache    cache stores
├── next-rust-core     config, .env loading, diagnostics
└── next-rust-assets   hashing, MIME types, CSS processing
examples/              small runnable apps, each with tests
skills/next-rust/      the skill that teaches AI tools this framework
website/               the documentation site, built with Next Rust
benchmarks/            the benchmark harness
```

To see how a request travels through all of that, read the Architecture page
of the [documentation](#documentation).

## Contributing

Next Rust is built in the open, and it only gets good if people other than
its first authors shape it. Every kind of contribution helps: a bug report, a
confusing error message you ran into, a docs fix, an example, or a whole
feature.

Some good places to jump in:

- **Automated WASM builds for client components.** The protocol exists;
  running `cargo` and `wasm-bindgen` for you doesn't yet.
- **Image resizing** and WebP output behind the existing `Image!` component.
- **Native TLS**, so small deployments don't need a proxy.
- **Browser tests** for client-side navigation and islands.
- **Windows.** Nobody has verified it yet.
- **Error messages.** If one confused you, it will confuse someone else.
  Tell us, or improve it.

Getting set up:

```sh
cargo test --workspace
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo fmt --all
```

Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. It
covers how changes are proposed, what we look for in reviews, and how to
report security issues privately.

If you're unsure whether an idea fits, open an issue and ask. Questions are
contributions too.

## Documentation

The documentation is a website built with Next Rust itself, in
[`website/`](website). It covers installation, routing, rendering, server
actions, deployment and every configuration option, with search. To read it
locally:

```sh
cd website
next-rust dev        # http://localhost:3000/docs
```

`next-rust build` in that folder produces the whole site as one binary, ready
to deploy. The site is pure Rust: each page is a module in
[`website/src/content/`](website/src/content) written with the same view
macros your app uses.

## Building with an AI coding agent

If you use Claude, Cursor, Copilot, Windsurf or any other AI coding tool, install
the Next Rust skill first. It teaches the tool this framework: the filenames and
export names that are compile-time contracts, the view macros, loaders, server
actions, the CLI and every configuration key, and how to work on the framework
itself. Without it, tools guess from Next.js or Axum and produce code that does
not compile.

The skill lives in [`skills/next-rust/`](skills/next-rust) and is plain Markdown,
so anything can read it.

**Claude Code, Claude Desktop, claude.ai**

```sh
git clone https://github.com/iplustsolution/next-rust
mkdir -p ~/.claude/skills
cp -r next-rust/skills/next-rust ~/.claude/skills/
```

That is it — the skill is offered automatically when a task involves Next Rust.
For one project only, copy it to `.claude/skills/` inside that project instead.

**Cursor, GitHub Copilot, Windsurf, Zed, Cline and similar**

These read a project instructions file. Copy the folder into your project:

```sh
cp -r next-rust/skills/next-rust my-app/skills/next-rust
```

then point your tool's instructions file at it with one line:

```md
For any work in this repository, read skills/next-rust/SKILL.md first and follow it.
```

Put that in `AGENTS.md`, `.cursor/rules/next-rust.mdc` or
`.github/copilot-instructions.md`, whichever your tool reads. This repository
ships an [`AGENTS.md`](AGENTS.md) that already does it.

**Any other agent, API integration, or a plain chat**

Paste [`skills/next-rust/SKILL.md`](skills/next-rust/SKILL.md) into the system
prompt or attach it to the conversation, and add the file from
[`skills/next-rust/references/`](skills/next-rust/references) that the task needs.

See [`skills/next-rust/README.md`](skills/next-rust/README.md) for what the skill
covers and how to keep it accurate.

## License

Next Rust is available under either the [MIT license](LICENSE-MIT) or the
[Apache License 2.0](LICENSE-APACHE), at your option. Unless you say
otherwise, any contribution you submit is licensed the same way.

Next Rust is inspired by the file-based routing popularized by Next.js. It's
an independent project, not affiliated with Vercel, and it contains no code
from Next.js or React.

---

<p align="center">
  <a href="https://www.iplust.in/">
    <img src="https://www.iplust.in/logo.png" alt="I Plus T Solution" height="48">
  </a>
</p>

<p align="center">
  Handled and managed by <a href="https://www.iplust.in/"><strong>I Plus T Solution</strong></a>
</p>