upcoming.js 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amir.Mahdi Sultani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/generator.js

@@ -0,0 +1,20 @@
+export function generateRoutesModule(routes) {
+
+    const imports = routes.map((route, index) => {
+      return `const Page${index} = lazy(() => import('${route.file}'))`
+    }).join('\n')
+  
+    const routeItems = routes.map((route, index) => {
+      return `  { path: '${route.path}', element: React.createElement(Page${index}) }`
+    }).join(',\n')
+  
+    return `
+  import React, { lazy } from 'react'
+  
+  ${imports}
+  
+  export const routes = [
+  ${routeItems}
+  ]
+    `.trim()
+  }

package/index.js

@@ -0,0 +1,80 @@
+import path from 'path'
+import { scanRoutes } from './scanner.js'
+import { generateRoutesModule } from './generator.js'
+
+const VIRTUAL_MODULE_ID = 'virtual:upcoming'
+const RESOLVED_ID = '\0virtual:upcoming'
+
+export default function upcoming(options = {}) {
+
+  const routesDir = options.routesDir
+    ? path.resolve(process.cwd(), options.routesDir)
+    : path.resolve(process.cwd(), 'src')
+
+  let generatedModule = ''
+
+  return {
+    name: 'upcoming.js',
+
+    buildStart() {
+      const routes = scanRoutes(routesDir)
+      generatedModule = generateRoutesModule(routes)
+    },
+
+    resolveId(id) {
+      if (id === VIRTUAL_MODULE_ID) {
+        return RESOLVED_ID
+      }
+    },
+
+    load(id) {
+      if (id === RESOLVED_ID) {
+        return generatedModule
+      }
+    },
+
+   
+    configureServer(server) {
+      const reload = (filePath) => {
+        const isPageFile = /page\.(jsx?|tsx?)$/.test(filePath)
+        const isNotFoundFile = /notfound\.(jsx?|tsx?)$/.test(filePath)
+
+        if (isPageFile || isNotFoundFile) {
+          const routes = scanRoutes(routesDir)
+          generatedModule = generateRoutesModule(routes)
+
+          const virtualModule = server.moduleGraph.getModuleById(RESOLVED_ID)
+          if (virtualModule) {
+            server.moduleGraph.invalidateModule(virtualModule)
+          }
+
+          server.ws.send({ type: 'full-reload' })
+        }
+      }
+
+     
+      server.watcher.on('add', reload)
+
+    
+      server.watcher.on('unlink', reload)
+    },
+
+    handleHotUpdate({ file, server }) {
+      const isInRoutesDir = file.startsWith(routesDir)
+      const isPageFile = /page\.(jsx?|tsx?)$/.test(file)
+      const isNotFoundFile = /notfound\.(jsx?|tsx?)$/.test(file)
+
+      if (isInRoutesDir && (isPageFile || isNotFoundFile)) {
+        const routes = scanRoutes(routesDir)
+        generatedModule = generateRoutesModule(routes)
+
+        const virtualModule = server.moduleGraph.getModuleById(RESOLVED_ID)
+        if (virtualModule) {
+          server.moduleGraph.invalidateModule(virtualModule)
+        }
+
+        server.ws.send({ type: 'full-reload' })
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "upcoming.js",
+  "version": "1.0.0",
+  "main": "index.js",
+  "type": "module",
+  "exports": {
+    ".": "./index.js",
+    "./runtime": "./runtime/Router.jsx"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "vite",
+    "react",
+    "file-based-routing",
+    "router",
+    "next.js",
+    "upcoming",
+    "upcoming.js",
+    "next",
+    "js",
+    "javascript",
+    "node",
+    "node.js",
+    "react-router",
+    "react-router-dom",
+    "next.js-routing"
+  ],
+  "author": "Amir.Mahdi Sultani",
+  "license": "MIT",
+  "description": "a plugin package for react vite for adding the file and folder based routing feature based according to nextjs",
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18",
+    "react-router": "^7.13.1",
+    "vite": ">=4"
+  },
+  "dependencies": {
+    "chalk": "^5.6.2"
+  }
+}

package/readme.md

@@ -0,0 +1,319 @@
+
+
+<div align="center">
+<br />
+
+
+██╗   ██╗██████╗  ██████╗ ██████╗ ███╗   ███╗██╗███╗   ██╗ ██████╗
+██║   ██║██╔══██╗██╔════╝██╔═══██╗████╗ ████║██║████╗  ██║██╔════╝
+██║   ██║██████╔╝██║     ██║   ██║██╔████╔██║██║██╔██╗ ██║██║  ███╗
+██║   ██║██╔═══╝ ██║     ██║   ██║██║╚██╔╝██║██║██║╚██╗██║██║   ██║
+╚██████╔╝██║     ╚██████╗╚██████╔╝██║ ╚═╝ ██║██║██║ ╚████║╚██████╔╝
+ ╚═════╝ ╚═╝      ╚═════╝ ╚═════╝ ╚═╝     ╚═╝╚═╝╚═╝  ╚═══╝ ╚═════╝
+
+```
+
+```
+
+### File-based routing for React + Vite. Inspired by Next.js. Built for those who love React.
+
+<br />
+
+
+[![npm version](https://img.shields.io/npm/v/upcoming.js?color=black&style=flat-square)](https://www.npmjs.com/package/upcoming.js)
+[![npm downloads](https://img.shields.io/npm/dm/upcoming.js?color=black&style=flat-square)](https://www.npmjs.com/package/upcoming.js)
+[![license](https://img.shields.io/npm/l/upcoming.js?color=black&style=flat-square)](https://github.com/amirmahdi390/upcoming.js/blob/main/LICENSE)
+[![github](https://img.shields.io/badge/github-upcoming.js-black?style=flat-square&logo=github)](https://github.com/amirmahdi390/upcoming.js)
+
+<br />
+
+</div>
+---
+
+---
+
+
+---
+
+---
+
+## Why I Built This
+
+I love Next.js's file-based routing. The idea of just creating a folder and a file and having a route automatically appear — no configuration, no imports, no `<Route>` declarations — is genuinely brilliant.
+
+**But I don't want to use Next.js.**
+
+I want React. I want Vite. I want the speed, the freedom, and the simplicity of a plain React project — without being forced into a full framework just to get one feature I love.
+
+So I built **upcoming.js** — Next.js-style file routing, for React + Vite. Nothing more, nothing less.
+
+---
+
+## What is upcoming.js?
+
+**upcoming.js** is a Vite plugin that watches your folder structure and automatically generates routes for React Router — no setup, no manual route declarations, no `<BrowserRouter>` wiring.
+
+You create folders. It creates routes.
+
+```
+src/
+├── page.jsx          →   /
+├── about/
+│   └── page.jsx      →   /about
+├── blog/
+│   ├── page.jsx      →   /blog
+│   └── [id]/
+│       └── page.jsx  →   /blog/:id
+└── notfound.jsx      →   404
+```
+
+That's it. That's the whole idea.
+
+---
+
+## Features
+
+* 📁 **Folder-based routing** — your file structure is your route structure
+* ⚡ **Vite plugin** — zero config, plugs directly into your existing Vite setup
+* 🔄 **Live route updates** — add or delete a `page.jsx` and the routes update instantly, no server restart needed
+* 🔀 **Dynamic routes** — `[param]` folders become `:param` in the URL
+* 🗂️ **Route groups** — `(group)` folders organize your code without affecting the URL
+* 🙈 **Private folders** — `_folder` folders are completely ignored by the router
+* 🚫 **404 pages** — just create `notfound.jsx` at the root of your routes folder
+* 💤 **Lazy loading** — every page is automatically code-split and lazy loaded
+* 🤝 **React Router powered** — all navigation, params, and hooks work exactly as you already know
+
+---
+
+## Installation
+
+```bash
+npm install upcoming.js
+```
+
+> **upcoming.js** will automatically install `react-router` as a dependency.
+> Make sure you have `react`, `react-dom`, and `vite` already in your project.
+
+---
+
+## Setup
+
+### 1. Add the plugin to `vite.config.js`
+
+```js
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import upcoming from 'upcoming.js'
+
+export default defineConfig({
+  plugins: [
+    react(),
+    upcoming()
+  ],
+  resolve: {
+    dedupe: ['react', 'react-dom', 'react-router']
+  }
+})
+```
+
+> The `dedupe` line prevents duplicate React instances — always include it.
+
+### 2. Replace your `src/main.jsx`
+
+```jsx
+import ReactDOM from 'react-dom/client'
+import { UpcomingRouter } from 'upcoming.js/runtime'
+
+ReactDOM.createRoot(document.getElementById('root')).render(
+  <UpcomingRouter />
+)
+```
+
+Done. No `App.jsx`, no `<BrowserRouter>`, no route declarations. Just run `npm run dev`.
+
+---
+
+## Folder & File Conventions
+
+### `page.jsx` — defines a route
+
+Every route is a `page.jsx` (or `page.js`) file. The folder path becomes the URL.
+
+```
+src/page.jsx                   →  /
+src/about/page.jsx             →  /about
+src/settings/account/page.jsx  →  /settings/account
+```
+
+---
+
+### `[param]` — dynamic segments
+
+Wrap a folder name in square brackets to make it a dynamic route parameter.
+
+```
+src/blog/[id]/page.jsx         →  /blog/:id
+src/shop/[category]/page.jsx   →  /shop/:category
+src/user/[id]/posts/page.jsx   →  /user/:id/posts
+```
+
+Accessing the param works exactly like React Router:
+
+```jsx
+import { useParams } from 'react-router'
+
+export default function BlogPost() {
+  const { id } = useParams()
+  return <h1>Post ID: {id}</h1>
+}
+```
+
+---
+
+### `(group)` — route groups
+
+Wrap a folder name in parentheses to group routes without affecting the URL. Great for organizing by feature or layout without polluting the URL.
+
+```
+src/(auth)/login/page.jsx      →  /login
+src/(auth)/signup/page.jsx     →  /signup
+src/(dashboard)/home/page.jsx  →  /home
+```
+
+---
+
+### `_folder` — private folders
+
+Prefix a folder name with `_` to exclude it from routing entirely. Use this for shared components, utilities, or anything that lives inside your routes folder but is not a route.
+
+```
+src/_components/Navbar.jsx     →  ignored
+src/_utils/helpers.js          →  ignored
+src/about/page.jsx             →  /about  ✓
+```
+
+---
+
+### `notfound.jsx` — 404 page
+
+Place a `notfound.jsx` at the root of your routes folder to handle unmatched routes.
+
+```
+src/notfound.jsx               →  * (catches all unmatched routes)
+```
+
+```jsx
+export default function NotFound() {
+  return <h1>404 — Page not found</h1>
+}
+```
+
+---
+
+## Navigation
+
+Navigation works exactly like React Router. **upcoming.js** is just an API on top of it — all hooks and components are the same.
+
+```jsx
+import { Link, useNavigate, useParams, useLocation } from 'react-router'
+
+// Link component
+<Link to="/about">About</Link>
+
+// Programmatic navigation
+const navigate = useNavigate()
+navigate('/blog/123')
+
+// Route params
+const { id } = useParams()
+
+// Current location
+const location = useLocation()
+```
+
+---
+
+## Configuration Options
+
+```js
+upcoming({
+  routesDir: 'src'  // the folder to scan for routes — default is 'src'
+})
+```
+
+If you use a feature-based architecture or want routes in a different folder:
+
+```js
+upcoming({
+  routesDir: 'src/pages'
+})
+```
+
+---
+
+## Custom Loading State
+
+You can pass a custom loading component that shows while lazy-loaded pages are being fetched:
+
+```jsx
+<UpcomingRouter loading={<div>Loading...</div>} />
+```
+
+---
+
+## Full Example Structure
+
+```
+src/
+├── page.jsx                     →  /
+├── notfound.jsx                 →  404
+├── about/
+│   └── page.jsx                 →  /about
+├── blog/
+│   ├── page.jsx                 →  /blog
+│   └── [id]/
+│       └── page.jsx             →  /blog/:id
+├── (auth)/
+│   ├── login/
+│   │   └── page.jsx             →  /login
+│   └── signup/
+│       └── page.jsx             →  /signup
+├── shop/
+│   └── [category]/
+│       └── [product]/
+│           └── page.jsx         →  /shop/:category/:product
+└── _components/
+    └── Navbar.jsx               →  ignored
+```
+
+---
+
+## Requirements
+
+| Dependency | Version |
+| ---------- | ------- |
+| React      | ≥ 18   |
+| React DOM  | ≥ 18   |
+| Vite       | ≥ 4    |
+
+---
+
+## Links
+
+* 📦 [npm](https://www.npmjs.com/package/upcoming.js)
+* 🐙 [GitHub](https://github.com/amirmahdi390/upcoming.js)
+
+---
+
+## License
+
+MIT © [Amir.Mahdi Sultani](https://github.com/amirmahdi390)
+
+---
+
+<div align="center">
+
+
+**If upcoming.js saved you time, give it a ⭐ on [GitHub](https://github.com/amirmahdi390/upcoming.js)**
+
+</div>

package/runtime/Router.jsx

@@ -0,0 +1,18 @@
+import { Suspense } from 'react'
+import { BrowserRouter, useRoutes } from 'react-router'
+import { routes } from 'virtual:upcoming'
+
+function AppRoutes() {
+  const element = useRoutes(routes)
+  return element
+}
+
+export function UpcomingRouter({ loading = <div>Loading...</div> }) {
+  return (
+    <BrowserRouter>
+      <Suspense fallback={loading}>
+        <AppRoutes />
+      </Suspense>
+    </BrowserRouter>
+  )
+}

package/scanner.js

@@ -0,0 +1,87 @@
+import fs from "fs"
+import path from "path"
+import chalk from "chalk"
+export function scanRoutes(routesDir) {
+   
+    let routesObject = [
+       
+    ]
+    
+    function folderChecker(folderPath) {
+    
+        let folders = fs.readdirSync(folderPath)
+    
+        folders.forEach(folder => {
+    
+            let fullPath = path.join(folderPath, folder)
+    
+            let stat = fs.statSync(fullPath)
+            
+    
+            if (stat.isDirectory()) {
+            
+              
+                if (!folder.startsWith("_")) {
+                    
+                    
+                folderChecker(fullPath)
+                }
+    
+            } else {
+                let fileName = path.basename(fullPath).toLowerCase()
+                if (fileName == "page.jsx"|| fileName == "page.js") {
+                  
+                    let route = `${path.relative(routesDir,path.dirname(fullPath)).replace(/\\/g,"/")}`;
+                   
+                    let sp = route.split("/")
+                    let routes = sp.map((r)=>{
+                        if (r.includes("(") && r.includes(")")) {
+                            return null
+                        }
+                        if (r.includes("[")&& r.includes("]")) {
+                            let a = `:${r.replace(/\[|\]/g,"")}`
+                            return a
+                        }else{
+                            return r
+                        }
+                       
+                    
+                    }).filter(Boolean)
+                    let finallr =`/${ routes.join("/")}`
+                    
+                    
+                    let routeOBJ = {
+                        path:finallr,
+                        file:fullPath.replace(/\\/g, "/")
+                    }
+                    routesObject.push(routeOBJ)    
+    
+                }
+               
+                if(fileName == "notfound.js" || fileName == "notfound.jsx" ){
+                    let filePath = path.dirname(fullPath)
+                    let rel = path.relative(routesDir,filePath).replace(/\\/g, "/")
+                   if (rel ==""){
+                    let notfoundOBJ = {
+                        path : "*",
+                        file:fullPath.replace(/\\/g, "/")
+                    }
+                    routesObject.push(notfoundOBJ)
+                    
+                   }
+                }
+               
+    
+            }
+    
+        })
+    
+    }
+    
+    folderChecker(routesDir)
+    console.log(chalk.blue("routes created successfully"));
+    
+    return routesObject
+    
+    
+}