!Video Showcase: Acaraje Demo

We all love new projects, right? I mean, at least the first few weeks are an incredible time to be working. The team starts discussing an idea, and suddenly that idea takes hold in the minds of all its members.

  • What will the stack be?
  • What will the database schema look like?
  • Who is this product for?
  • How can we make the UI/UX intuitive?

And the other questions we throw at each other for a couple of weeks, imagining that this will be the project of our lives. But then reality wakes us up and leaves us with a scary realization… we actually need to build it, right?

The Developer Loop of Every Project

After that realization, you take all those fancy graphs, flowcharts, and pre-project documentation and get to work. Let’s say you’re building the new marketplace that’s totally going to replace Amazon. You start with the Sign Up page, then the user’s profile page, the cart interface, the product interface, and so on, until you hit a roadblock and think to yourself, “Wait, I need entries in my database to test all of this, but I have none.” So you manually create a couple of users and products, and maybe find time to write a few test scripts to seed the database, among other things. Then eventually you realize you need to track metrics too, like monthly sales or the app’s growth percentage. All of that for the team lead says: “We evaluated some things with our clients; we need to change the database.”

I’m sure every developer has had that experience, and it’s frustrating that every new app starts with the same CRUDs, graphs and storage phase as the last one. It is not always that we can reuse code from other projects, and although AI has improved this a lot, we still have to wait for the agents to work, review their code, and ultimately spend money on tokens for something that is, by nature, repetitive.

But what if we had a way to generate an admin panel with a single terminal line? What if that tool had better usability and a better understanding of your schema than the standard database apps we’re used to? And, on top of that, what if it handed you the source code to extend however you needed?

Introducing Acaraje Admin Panel

The idea for Acaraje came directly out of the frustration described above. Early development should be simple. You need to move fast and test the app’s flow before worrying about anything that only serves the admin side. That’s exactly what Acaraje is: a shortcut that generates a full admin panel so you can build faster.

Stack

Acaraje was initially the admin panel for one of my own Prisma projects, but I eventually realized it could be reused across future projects. Because of that, its stack reflects the technologies used in that original project, and it’s built on top of Next.js. It might feel too mainstream (my personal taste would agree), but I chose tools that most developers already have some experience with, so either I or another developer could extend it without much friction.

Layer Technology Reason
Framework Next.js 15 (App Router), React 19, TypeScript Next.js is straightforward, simple, and easy. In my opinion, it’s the quickest way to build a full-stack app with a good UI.
Styling Tailwind CSS, Radix UI primitives, lucide-react icons Tailwind is a must. The rest came from shadcn/ui, which is effective and highly customizable.
Data fetching TanStack Query I considered tRPC or Redux Toolkit (which I’m more familiar with), but decided to keep things simple.
Tables & Forms TanStack Table, TanStack Form Since I was already using TanStack Query, it made sense to use the rest of the TanStack ecosystem too.
Validation Zod I don’t think this needs much explanation; Zod is excellent for type validation.
ORM / DB access Prisma or Kysely (raw SQL), depending on the setup The original project was built on Prisma; I added Kysely later for more generic, ORM-free projects.
File storage MinIO (S3-compatible) or Google Cloud Storage Covers the most common storage solutions, and both work well in local Docker development.
Seeding @faker-js/faker Faker is simple and gives you a lot of control over fake data.
Auth Signed session cookie, env-configured single admin account Designed this way so it doesn’t impose assumptions on the user’s schema.

A bit more detail on some of these choices:

  • Auth: This was one of the things I worried about most. As I mentioned, I didn’t want to dictate how the end user’s schema should look, and auth usually lives at the database level, so what should I do? Initially I considered skipping authentication entirely, both to forget about that problem and to reinforce the message of “this is a test environment, don’t publish it as-is; customize it as needed.” Most of the projects I’ll use Acaraje for are solo projects with long local-development phases, so that option looked even more appealing to me. But when I talked about the project with a coworker, he told me it would help him a lot on a project he’s building with his cousin, and even if it would only ever be exposed on an unlisted URL, it would still be prudent to have some form of auth. So I decided to implement it. My first instinct was to use NextAuth, which I wanted to try for a while, but every time the opportunity came up, the team ended up switching to something like Better Auth instead. As excited as I was to finally use it, once I started prototyping the project in my head, I realized it would be overkill for something I expect users to swap out later anyway. In the end, I kept auth as simple as possible and just added a warning in the README.

  • Storage management and Docker: The last straw that pushed me to build Acaraje was hitting a wall on another project. I was already unsatisfied, having to use Prisma Studio just to save time adding entries to the DB, when a new feature required proper storage logic for fetching assets. Needless to say, I was annoyed, since my focus should have been on 3D scene development, not building a cloud folder structure. I usually store assets in the cloud, but this time I wanted to keep everything inside Docker. MinIO looked like the best fit, especially given its S3 compatibility in case I wanted to try that route later. I also wanted the option to store files on Google Cloud, even though my current setup was local, so I found fake-gcs-server, and the rest was just a matter of adding the option to choose between the two in the project. Because of that, the CLI lets you use Docker for local development, generating a docker-compose.yml that matches your chosen setup.

  • Styling: I’ll start by saying CSS is miserable. I mean, I guess the whole frontend experience is miserable, which is exactly why we have frameworks like the ones we do. But CSS in particular is frustrating to edit, review, and maintain, so the best approach is to know exactly what a component looks like just by reading its declaration. I know that sounds like Bootstrap all over again, but Tailwind gets it right this time by being far more customizable, and, oddly enough, more verbose. Side note: I used to tolerate styled-components more than most other solutions, but it has its own problems, and it’s now in maintenance mode, so… RIP styled components. As for the rest, I like that shadcn/ui is customizable, only installs what you need, has a nicely understated look, and is fully Tailwind-compatible.

  • Frontend: Next.js is the standard because it has everything going for it: easy routing, server components and actions, solid caching, simple middleware configuration, Vercel integration, and more. I think we’re past the point of criticizing people for using React, and it’s fair to admit that Solid.js remains a niche choice. There’s not much more to say, except that nearly everyone has already worked on a Next.js project, which makes for a better editing experience for the end user.

  • TanStack: I’ll admit I’m biased toward Redux. I genuinely love the boilerplate, the ten files you have to configure every time you start a new project, that you always forget how to write, so you either dig through the docs or copy-paste from an old project. Wonderful, honestly. But in all seriousness, I like Redux, and using it alongside RTK Query has generally worked well for me. That said, I decided to stuck with the more standard choice. My experience with React Query itself is limited (and mostly relegated to tRPC’s implementation), so this will be a good opportunity to get more familiarized with it. The rest of the TanStack suite was included by default, though I do think React Hook Form is a better tool than TanStack Form.

  • Prisma & Kysely: I remember Drizzle gaining popularity a while back, and I’ve used it myself. It’s indeed good. I like having my schema defined in a .ts file, and it hasn’t given me nearly as many headaches as Prisma. That said, Prisma schemas are easier to write, Prisma has been around longer, has a bigger ecosystem, I prefer its query syntax to Drizzle’s, it has MongoDB support (really lacking, but still), and overall it’s still a solid experience. Kysely was added because the coworker I mentioned earlier wanted to use Acaraje on a project with no ORM at all, so he asked me to add support for generating the dashboard from a plain .sql file. I do think about adding Drizzle support eventually, but I know it’ll be more difficult than the Kysely implementation, so I’ll be putting in the backlog for now. Side note: I’d also like to add MongoDB and other databases down the line.

Future Updates

I’ll keep updating Acaraje over time. There’s a lot more I’d like to add to the repository, but right now my focus is on my other projects (which is the whole reason I built this in the first place). That said, I’m on a mission to make at least one meaningful commit on GitHub every day (meaningful, because committing a README tweak every day would feel like cheating), so I imagine this will end up being the repo I return to for small fixes and features over time.

Here’s what’s planned for future releases:

  • More CLI commands: Right now the only available command is npx acaraje init, and that’s not much. I could argue that Acaraje is meant to be exactly that: a one-line dashboard you customize and then forget about the cli, and there’s some truth to that. But there’s still a lot that could be added to support user customization. For example, if a user changes their schema, what should they do? They could re-run init, but that could be problematic, especially if they’ve already started editing the generated code (the same goes for update commands in general). So instead of regenerating or updating everything at once, updates should happen in steps, letting users choose to individually update the generated parsed-schema.ts, the CRUDs, the seeding logic, and so on according to their needs. I’m also considering adding CLI seeding commands for the panel, but I’m still undecided.

  • Graphs: I actually tried this before turning the project into a CLI, and the results were terrible. Not because it didn’t work, but because building the graphs through the interface I’d made was far too complicated. Acaraje is meant to be generalist, which makes it hard to build something that depends heavily on the specific relationships in a given schema. In short, it could result in atrocities like generating a pie chart out of user emails. To be honest, in cases like that it’s just easier to build the chart by hand or ask Claude to do it. So my best plan is to build reusable graph components and ship them alongside a Claude.md file with instructions for building graphs from them.

  • Themes: Minor, but I’m honestly tired of the current color scheme. It’s not bad, exactly, I’d just like to have more variety.

  • Claude markdown: I don’t have much experience generating a Claude.md file, especially one meant for the generated panel rather than the CLI project itself. But there’s a first time for everything, right?

  • Vercel Blob direct integration: If I’m not mistaken Vercel uses S3 under the hood, but its API isn’t S3-compatible, meaning it doesn’t support MinIO. I use Vercel a lot, so this is a priority for me.

Final Considerations

Projects are usually built to solve one person’s pain point, and Acaraje was built to solve a pain point shared by many developers who struggle to kickstart their projects. It gives you everything you need to manage your database and storage before you even get started, and hands you the source code so you can customize it however you like.

I built this because I was tired of solving the same problem over and over on every new project, and I figured if it saved me that much time, it was worth turning into something other people could use too. It’s still early, there are rough edges, and the roadmap above is long, but the core idea already works: run one command, get a working admin panel, and get back to building the part of your app that actually matters.

If that sounds useful, give it a try:

npx acaraje init

The source is code is here

And for anyone wondering: the name Acaraje comes from a delicious West African and Northeastern Brazilian dish, and I’m genuinely upset that nobody sells it here in the US. If you know a place, tell me. I’ll consider it a fair trade for the CLI.