How to structure a full-stack React + Motoko dApp on the Internet Computer

VaultyPDF — Fri, 13 Nov 2026 04:42:20 +0000

Hey builders,

When you first start building on the Internet Computer Protocol (ICP), getting a basic "Hello World" canister running is pretty straightforward. The real headache starts when you try to scale that into a full-stack SaaS application with a multi-tool React frontend, user state tracking, and clean file handling.

While building VaultyPDF (a 15-tool on-chain PDF utility suite), I had to reorganize my project several times before finding a structure that didn't turn into spaghetti code. Here is the clean folder architecture I landed on for pairing React with Motoko.

1. Keep Backend Canisters Modular

Instead of stuffing thousands of lines of logic into a single main.mo file, separate your data types and helper functions early on:

src/
├── backend/
│   ├── main.mo          # Main entry point & public actor methods
│   ├── types.mo         # Custom user & document metadata types
│   └── storage.mo       # Stable memory & state management helpers

Using a dedicated types.mo file makes it much easier to keep your Motoko records aligned with your frontend JavaScript/TypeScript interfaces.

2. Isolate Frontend Canister Calls

Never call your backend actor directly inside your UI components. Create a dedicated service or hook layer in your React folder so your UI stays focused purely on rendering:

src/
├── frontend/
│   ├── src/
│   │   ├── components/  # Reusable dark-mode UI cards & modals
│   │   ├── hooks/       # Custom hooks for auth & canister queries
│   │   ├── pages/       # Individual tool views (Merge, Split, Redact)
│   │   └── App.jsx      # Main dashboard layout & routing

3. Handle Heavy Client-Side Processing Locally

On-chain storage and compute are great for user profiles, audit logs, and document metadata. However, for heavy PDF manipulation (like merging pages or applying visual redactions), run the heavy lifting directly in the user's browser via JavaScript, and only send the verified metadata or final state hashes to your Motoko canister. This keeps your cycle burn rate low and makes the UI feel instant.

Want to skip the boilerplate setup?

Setting up the React routing, dark-mode SaaS dashboard UI, and Motoko canister bindings from scratch easily eats up a couple of weeks.

If you want a ready-to-deploy foundation for your own ICP project, I packaged my entire 15-tool codebase into a clean starter template:

👉 Check out the VaultyPDF React + Motoko Boilerplate on Gumroad

How do you guys usually organize your Motoko projects when the codebase starts growing? Drop your folder tips below!

I built a 15-tool PDF suite running 100% on-chain with React and Motoko

VaultyPDF — Thu, 12 Nov 2026 12:02:54 +0000

Hey everyone,

Most web-based PDF tools upload your private files to a random backend server just to merge a couple of pages or add a signature. I wanted to see what it would look like to build an all-in-one PDF utility suite that runs completely serverless on the Internet Computer Protocol (ICP).

After a lot of trial and error configuring the UI and backend logic, I finally wrapped up VaultyPDF.

What it actually does

Instead of building just a basic file converter, I packed 15+ everyday document utilities into a single dark-mode dashboard:

Core file handling: Merging, splitting, compressing, and page cropping.
Security & privacy: Permanent document redaction and on-chain e-signatures.
Tracking: Decentralized user metadata and file state tracking handled directly through Motoko canisters (main.mo).

The tech stack

Frontend: React with a clean, dark-mode SaaS dashboard layout.
Backend: Motoko canisters running on ICP for serverless execution without traditional cloud databases.

Turning it into a boilerplate

Setting up the frontend routing, dark-mode components, and Motoko canister connections from scratch took way longer than I expected. Since a lot of solo devs and indie hackers want to build micro-SaaS apps on ICP without spending weeks on boilerplate layout code, I cleaned up the repo and packaged it as a starter template.

If you are building on ICP or just want to save yourself 100+ hours of frontend and canister setup, you can check out the full source code bundle here:

👉 Grab the VaultyPDF React + Motoko Boilerplate on Gumroad

Would love to hear what you guys think about running heavy document workflows on-chain, or if anyone else here is building SaaS tools with Motoko!

DEV Community: VaultyPDF