# BlinkShot: a real-time image generator built to be cloned, not deployed

> An open source Next.js image generator that streams Juggernaut Lightning Flux output through Together AI, with Braintrust tracing and Upstash rate limiting. Its README is candid about what is still on the to-do list.

**Nutlope/blinkshot** — A realtime AI image generator

- Repository: https://github.com/Nutlope/blinkshot
- Website: https://www.blinkshot.io/
- Stars: 1,041 · Forks: 193
- Language: TypeScript
- License: not declared
- Published: 2026-10-07 · Updated: 2026-10-07 · Language: en
- Canonical page: https://hysenlabs.com/projects/nutlope-blinkshot

## What the repository actually contains

BlinkShot is a Next.js app with a small, conventional tree: `app/` for routes, `components/`, `hooks/`, `lib/`, `public/`, and a `scripts/` directory that matters more than its size suggests. Configuration lives in `next.config.mjs`, `tailwind.config.ts` and `postcss.config.mjs`, with `eslint.config.mjs` and `components.json` for the component layer. The package manager is pnpm, and `pnpm-lock.yaml` is committed alongside `package.json`.

Two root files are worth noticing because they are unusual for a demo. `proxy.ts` sits at the top level rather than inside the app directory, and `.example.env` is checked in as a template.

The project has 1,039 stars and 191 forks with zero open issues, and it is not archived. The last push was on 2026-08-31. There are no releases and no version tags, so the `version` field in `package.json` reads `0.1.0` and the project is marked `private`, which for a Next.js app means private to npm rather than closed source.

The homepage is blinkshot.io, which is the hosted version built from this code.

## Getting it running takes one API key

The README's setup section is three numbered steps, and the first two are about credentials rather than tooling.

```bash
git clone https://github.com/Nutlope/blinkshot
```

Then create a `.env.local` file and add your Together AI API key, then run `npm install` and `npm run dev` to install dependencies and run locally. The `.example.env` file in the tree is the template for that environment file.

That is the entire dependency on an external service. There is no database, no object storage and no queue. Images are produced by a model and streamed to the browser, and the persistence problem is unsolved, which the README confirms by listing a download button as unfinished work.

The test and verification scripts are where this repo is more rigorous than a typical demo. Alongside the standard `dev`, `build`, `start` and `lint` scripts, `package.json` defines a test script that runs `tsx` against `lib/**/*.test.ts`, and two verify scripts: one for Braintrust traces and one for the model catalog.

## A two-step Flux model behind an event stream

The model choice is specific and the README says why. BlinkShot is powered by Juggernaut Lightning Flux from RunDiffusion, served through Together AI. The Together AI link in the README carries referral parameters, which is worth noting as a fact about the project's incentives rather than an accusation about the code.

Lightning Flux is a distilled few-step model, and the README's future list confirms this by including a setting to select between 2 and 5 steps. Fewer steps is the entire reason a generator can feel instant, so this is the parameter that determines whether the app feels real-time or feels like a loading screen. It is not implemented yet, which means the current latency profile is whatever the default step count gives you.

The dependency list in `package.json` tells you more about the stack than the README does. It includes `@radix-ui/react-*` primitives for dialogs, selects, radio groups and switches, `@tanstack/react-query` for server state, `embla-carousel-react` for carousel behaviour, `lucide-react` for icons, `react-hot-toast` for notifications, and `@upstash/redis` with `@upstash/ratelimit` for distributed rate limiting. Versions are current: Next 16.2.6, React 18, Tailwind merge 2.5.

Two entries are easy to skim past. `server-only` is a dependency, which is the package that throws if a module marked server-only is imported into client code, so image generation is deliberately kept off the client bundle. And `dedent` is present, which is a hint that prompts are stored as template literals rather than string concatenation.

## Tracing every generation with Braintrust

BlinkShot integrates Braintrust for image-generation tracing and observability, and treats it as a first-class concern rather than an afterthought. The `braintrust` package sits at 3.21.0 in the dependencies, and there is a dedicated verification script, `verify:braintrust`, whose only job is to check that a trace can be produced.

Having a script that verifies observability separately is the detail worth taking seriously. Most projects that claim tracing never prove the trace arrives. A verify script means a misconfigured key or a renamed export breaks a check rather than silently producing a working-looking app with no data behind it.

The same instinct shows up in `verify:models`, which checks the model catalog. Together the two scripts cover the two things most likely to break invisibly in an app whose entire visible output is an image: the model list going stale, and the trace pipeline going quiet.

Analytics are handled separately by Plausible, wired in through `next-plausible`. The split between Braintrust for backend traces and Plausible for page views is a normal division of labour, though it does mean two third-party services are involved in running your own instance.

## The future task list is a product spec

The README ends with six unchecked tasks, and reading them as a group tells you what a real deployment would need beyond this code.

The first is a download button, so people can get their images, which means image persistence that does not exist today. The second is auth and rate limiting by email instead of IP, which changes the `@upstash/ratelimit` key from an address to an identity. The third is showing users how many credits they have left, which implies a billing model that does not exist. The fourth is an image gallery of generations with their prompts, which implies storing both.

The last two are more technical. Replay functionality, so people can replay consistent generations, means storing enough state to reconstruct a seed and sampler setup. And a setting to select between steps, 2 to 5, is the latency control described earlier.

Read together, the gaps are consistent: the repository has the streaming pipeline and nothing around it. There is no account, no storage and no quota. That is a coherent thing to publish, since it is a reference implementation rather than a product, but it does mean anyone who clones this is starting from the middle of the stack.

The `husky` and linting setup suggest the project intends contributors, and the `components.json` file indicates shadcn-style components are part of the house style, though the README does not spell out the component conventions in prose.

## Conclusion

BlinkShot is best read as a reference implementation of a streaming image generator rather than a service you would point users at. The plumbing is the point: a two-step Flux model behind a server-sent event stream, traced through Braintrust, rate limited through Upstash, with model and observability checks wired into package scripts so a misconfiguration surfaces as a failed verify rather than a blank image. What it does not have is everything on its own future list, including a download button, email-based limits, credit display and a prompt gallery, so running your own deployment means writing that layer. The repo is not archived and the last push was 2026-08-31, so the dependency list will move. Start by cloning it, adding a `TOGETHER_API_KEY` to `.env.local`, and running `npm run dev` to see the stream behave before deciding what to build on top.

## FAQ

### What model does BlinkShot use to generate images?

Juggernaut Lightning Flux from RunDiffusion, served through Together AI. The README notes that adding a control for 2 to 5 steps is still an open task, which is the main latency lever for a distilled model.

### How do I run BlinkShot locally?

Clone the repository, create a `.env.local` file containing your Together AI key as `TOGETHER_API_KEY`, then run `npm install` and `npm run dev`. An `.example.env` template is included in the repository root.

### Does BlinkShot need a database to store generated images?

No, and that is a known limitation rather than an oversight. A download button is listed as an unfinished task, so images currently exist only for the session that generated them.

### What is Braintrust used for in BlinkShot?

Image-generation tracing and observability. The package is a direct dependency and a `verify:braintrust` script exists specifically to confirm traces are being produced, so the observability path is checked rather than assumed.

### How does BlinkShot rate limit its users?

By IP address, using `@upstash/redis` and `@upstash/ratelimit`. Moving to auth with rate limiting by email instead of IP is listed as a future task.

## Sources

- [Issues](https://github.com/Nutlope/blinkshot/issues)
- [Nutlope/blinkshot on GitHub](https://github.com/Nutlope/blinkshot)
- [Project website](https://www.blinkshot.io/)
- [README](https://github.com/Nutlope/blinkshot/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nutlope-blinkshot