🔗 Nuto is a smart URL shortener designed to escape in-app browsers and open links where they belong: in the user's native browser or the corresponding native application.

The name "Nuto" comes from the Spanish word "diminuto" (tiny), reflecting its purpose of making long URLs tiny.

🤝🏻 This project's UI was highly influenced by Pheralb's slug. 🗿

📚 Table of Contents

• Key Features
• Tech Stack
• Getting Started
• Building for Production
• Deploying with Wrangler
• Roadmap
• Known Issues
• Related projects
• License

✨ Key Features

• In-App Browser Escape: Detects when a link is opened inside an in-app browser (like Instagram) and redirects to the native system browser.
• Deep Linking: Opens YouTube, Spotify, and other supported links in their native apps instead of the in-app browser.
• Password Protection: Secure your links with a password.
• Link Expiration: Set an expiration date for temporary links.
• Custom Short Codes: Users can customize the short code for their links.
• Click Analytics: Basic, privacy-friendly click tracking (no IP addresses are stored).
• User Authentication: Managed with Clerk for secure sign-in and user management.

🛠️ Tech Stack

• Framework: React Router v7 (Full-stack)
• Platform: Cloudflare
  • Deployment: Cloudflare Workers
  • Database: Cloudflare D1
  • Storage: Cloudflare KV for caching
• UI & Frontend:
  • Library: React with TypeScript
  • Styling: Tailwind CSS
  • Components: shadcn/ui (using Radix UI primitives)
  • Icons:
    • Lucide React
    • React Simple Icons
  • Notifications: Sonner
• Authentication: Clerk
• Tooling:
  • Build Tool: Vite
  • Package Manager: pnpm
  • CLI

🚀 Getting Started

Prerequisites

You will need the following to run Nuto locally:

• Node.js v22.14+
• pnpm v10.14+
• Wrangler CLI
• A Clerk account for authentication. Note: You must configure a Clerk Webhook with user management events for proper ID synchronization. See Clerk Webhooks docs.
• A Cloudflare account for D1 and KV.

1. Installation

git clone https://github.com/andesvel/nuto.git
cd nuto
pnpm install

2. Environment Setup

Create the required environment files.

.env.local (Client-side variables):

VITE_CLERK_PUBLISHABLE_KEY=pk_...

.dev.vars (Worker/Server-side secrets):

CLERK_SECRET_KEY="sk_..."
PASSCODE_ENC_KEY="..."
CLERK_WEBHOOK_SECRET="whsec_..."

3. Development Server

Start the Vite development server with HMR:

pnpm dev

Your application will be available at http://localhost:5173.

---

☁️ Deployment

Cloudflare Workers handles both the SSR routing (via React Router) and the API.

1. Build

pnpm build

2. Provision Cloudflare Resources (First time only)

Login to Cloudflare:

wrangler login

Create the D1 database:

wrangler d1 create nuto-db

(Update wrangler.jsonc with the new database_id)

Create the KV namespace (for production and preview):

wrangler kv namespace create URL_STORE
wrangler kv namespace create URL_STORE --preview

(Update wrangler.jsonc with the corresponding id and preview_id)

3. Configure Secrets

wrangler secret put CLERK_SECRET_KEY
wrangler secret put PASSCODE_ENC_KEY
wrangler secret put CLERK_WEBHOOK_SECRET

4. Initialize Database

Execute the schema against your D1 instance:

wrangler d1 execute nuto-db --file=./schema.sql

5. Deploy

pnpm deploy

🗺️ Roadmap

Here's a look at the current state and future plans for Nuto.

• ✅ Stable
• 🚧 In Development
• 🤔 To Be Decided (TBD)

Feature	Status	Details
Core Functionality	✅	URL shortening, redirection, and basic click tracking.
Link Management	✅	Create, view, edit, and delete links.
UI/UX	✅	Click-to-copy, status notifications, responsive design.
Security	✅	Password-protected links and expiration dates.
Authentication	🚧	GitHub login provider is currently in development.
Dashboard Analytics	🤔	Advanced stats: total links/clicks, click graphs, top links.
QR Codes	🤔	Generation and customization of QR codes for each link.

🐛 Known Issues

• PWA Layout: Some layout and styling issues may occur when the application is installed as a Progressive Web App (PWA), particularly around the header and safe areas on mobile devices.
• GitHub Authentication: The sign-in flow for GitHub is not currently functional and is being worked on.

🔗 Related projects

• slug - 🌱 An open-source URL shortener built with T3 Stack.
• midu.link - Create shorten urls easily with Cloudfare Workers.
• inapp-debugger - Test common in-app issues.
• inapp-spy - Detect in-app browsers.
• Bowser - A browser detector.
• Sink - A Simple / Speedy / Secure Link Shortener with Analytics, 100% run on Cloudflare.
• Kutt - Free Modern URL Shortener.
• ZWS - Shorten URLs using invisible spaces.

⚖️ License

This project is licensed under the GNU General Public License v3.0