next-build-filter 0.1.0 → 0.2.1

package/README.md

@@ -8,10 +8,11 @@ A powerful Next.js plugin that allows you to exclude specific pages/routes from
 - 📱 **App Router Support** - Full Next.js 13+ App Router compatibility
 - 📄 **Pages Router Support** - Traditional Pages Router support
 - 🎯 **Flexible filtering** with multiple configuration options
+- 🌟 **Glob Pattern Matching** - Use powerful wildcards like `admin/**`, `*/test`, `blog/*`, `**/internal/**`
 - 🔄 **Non-destructive** - files remain in your codebase
 - 🌍 **Environment-aware** - different configurations for dev/prod
 - 📝 **Verbose logging** to see what's being filtered
-- 🎨 **Pattern matching** support with regex
+- 🎨 **Advanced pattern matching** support with regex (for complex cases)
 - 🔧 **TypeScript support** with full type definitions
 
 ## Installation
@@ -34,8 +35,8 @@ const filterConfig = {
   supportPagesRouter: true,
   supportAppRouter: false,
   excludedPages: [
-    'admin',
-    'dev/debug',
+    'admin/**',    // Exclude all admin pages (supports glob patterns)
+    'dev/**',      // Exclude all dev pages
   ],
 };
 
@@ -56,8 +57,8 @@ const filterConfig = {
   supportAppRouter: true,
   supportPagesRouter: false,
   excludedPages: [
-    'admin',        // Excludes app/admin/page.tsx
-    'dev/debug',    // Excludes app/dev/debug/page.tsx
+    'admin/**',     // Excludes all routes under app/admin/ (glob pattern)
+    'dev/**',       // Excludes all routes under app/dev/
   ],
 };
 
@@ -81,8 +82,9 @@ const filterConfig = {
   supportAppRouter: true,
   supportPagesRouter: true,
   excludedPages: [
-    'admin',        // Excludes both pages/admin.js and app/admin/page.tsx
-    'dev/debug',    // Excludes both pages/dev/debug.js and app/dev/debug/page.tsx
+    'admin/**',     // Excludes both pages/admin/** and app/admin/** (glob pattern)
+    'dev/**',       // Excludes both pages/dev/** and app/dev/**
+    '**/internal',  // Excludes any route ending with /internal
   ],
 };
 
@@ -106,6 +108,30 @@ FILTER_PAGES=true npm run build
 npm run build:filtered
 ```
 
+## Glob Pattern Quick Reference
+
+The plugin supports powerful glob patterns for flexible page/route matching:
+
+| Pattern | What it matches | Example |
+|---------|----------------|---------|
+| `admin` | Exact match | `/admin` only |
+| `admin/*` | One level deep | `/admin/users`, `/admin/settings` |
+| `admin/**` | Any depth | `/admin/users`, `/admin/users/edit`, `/admin/settings/advanced` |
+| `**/test` | Ending with | `/api/test`, `/components/test`, `/admin/tools/test` |
+| `*/debug` | One wildcard | `/api/debug`, `/dev/debug` |
+| `**/internal/**` | Containing | Any route with `/internal/` anywhere in path |
+| `{admin,dev}/**` | Multiple patterns | All routes under `/admin` or `/dev` |
+
+**Example Usage:**
+```javascript
+excludedPages: [
+  'admin/**',        // ✅ Exclude all admin routes (recommended)
+  'dev/**/test',     // ✅ Exclude test pages in dev directory
+  '*-draft',         // ✅ Exclude pages ending with -draft
+  'api/*/internal',  // ✅ Exclude internal API routes
+]
+```
+
 ## Configuration Options
 
 ### Basic Options
@@ -127,7 +153,40 @@ npm run build:filtered
 
 ### Filtering Options
 
+The plugin supports three types of matching:
+1. **Exact Match** - Direct string matching
+2. **Glob Patterns** - Flexible wildcard matching (powered by [minimatch](https://github.com/isaacs/minimatch))
+3. **Regex Patterns** - Advanced pattern matching via `excludePatterns`
+
+#### Glob Pattern Syntax
+
+| Pattern | Description | Example Matches |
+|---------|-------------|-----------------|
+| `*` | Matches any characters except `/` | `blog/*` matches `blog/post1`, `blog/post2` but not `blog/category/post1` |
+| `**` | Matches any characters including `/` | `blog/**` matches `blog/post1`, `blog/category/post1`, `blog/a/b/c` |
+| `?` | Matches exactly one character | `user/?/profile` matches `user/a/profile`, `user/1/profile` |
+| `[abc]` | Matches any character in the brackets | `user/[0-9]/profile` matches `user/0/profile`, `user/5/profile` |
+| `{a,b}` | Matches any of the patterns | `{admin,dev}/**` matches `admin/users`, `dev/debug` |
+| `!` at start | Negation (not commonly used in this plugin) | `!admin/**` would match everything except admin routes |
+
+**Common Glob Patterns Cheat Sheet:**
+
+| Use Case | Pattern | Matches |
+|----------|---------|---------|
+| Exact page | `admin` | `/admin` only |
+| Direct children | `admin/*` | `/admin/users`, `/admin/settings` (not nested) |
+| All nested routes | `admin/**` | `/admin/users`, `/admin/users/edit`, `/admin/settings/advanced` |
+| Ends with | `**/test` or `**/*-test` | `/api/test`, `/users/profile-test` |
+| Starts with | `admin/**` or `admin*` | `/admin`, `/admin-panel`, `/admin/users` |
+| Contains | `**/internal/**` | Any path with `/internal/` segment |
+| Multiple patterns | `{admin,dev,test}/**` | All routes under `/admin`, `/dev`, or `/test` |
+| Specific file patterns | `**/*-draft` | `/blog/post-draft`, `/products/item-draft` |
+| API versioning | `api/v{1,2}/**` | `/api/v1/*`, `/api/v2/*` |
+| Wildcard in middle | `api/*/internal` | `/api/users/internal`, `/api/products/internal` |
+
 #### 1. Include Only Specific Pages
+
+**Exact Match:**
 ```javascript
 const filterConfig = {
   enabled: true,
@@ -139,7 +198,22 @@ const filterConfig = {
 };
 ```
 
+**Glob Pattern Matching:**
+```javascript
+const filterConfig = {
+  enabled: true,
+  includedPages: [
+    'index',           // Exact match: /
+    'blog/*',          // All direct children: /blog/post1, /blog/post2
+    'products/**',     // All nested routes: /products/*, /products/category/*, etc.
+    'user/*/profile',  // Wildcard in middle: /user/123/profile, /user/456/profile
+  ],
+};
+```
+
 #### 2. Exclude Specific Pages
+
+**Exact Match:**
 ```javascript
 const filterConfig = {
   enabled: true,
@@ -151,18 +225,52 @@ const filterConfig = {
 };
 ```
 
-#### 3. Pattern-Based Exclusion
+**Glob Pattern Matching:**
+```javascript
+const filterConfig = {
+  enabled: true,
+  excludedPages: [
+    'admin',           // Exact match: /admin
+    'admin/*',         // All admin sub-pages: /admin/users, /admin/settings
+    'admin/**',        // All nested admin routes: /admin/*, /admin/users/*, etc.
+    'dev/**',          // All dev routes: /dev/*, /dev/debug/*, etc.
+    '*/test',          // Any route ending with /test: /api/test, /dev/test
+    '**/internal/**',  // Any route containing /internal/
+  ],
+};
+```
+
+#### 3. Regex Pattern-Based Exclusion (Advanced)
+
+For complex patterns that can't be expressed with glob syntax, use `excludePatterns`:
 ```javascript
 const filterConfig = {
   enabled: true,
   excludePatterns: [
-    'dev/.*',          // All pages in /dev/ directory
-    '.*admin.*',       // Any page with 'admin' in the path
-    '.*test.*',        // Any page with 'test' in the path
+    'dev/.*',          // Regex: All pages in /dev/ directory
+    '.*admin.*',       // Regex: Any page with 'admin' in the path
+    '.*test.*',        // Regex: Any page with 'test' in the path
+    '^api/v[0-9]+/',   // Regex: API versioned routes like /api/v1/, /api/v2/
   ],
 };
 ```
 
+### Glob Patterns vs Regex Patterns
+
+Choose the right pattern type for your use case:
+
+| Use Case | Glob Pattern | Regex Pattern | Recommendation |
+|----------|--------------|---------------|----------------|
+| Exclude all admin routes | `admin/**` | `admin/.*` | ✅ Use Glob (simpler) |
+| Exclude routes ending with -test | `**/*-test` | `.*-test$` | ✅ Use Glob (simpler) |
+| Exclude versioned API routes (v1, v2) | N/A | `^api/v[0-9]+/` | ✅ Use Regex (complex pattern) |
+| Match any route containing 'internal' | `**/internal/**` | `.*internal.*` | ✅ Use Glob (simpler) |
+| Match routes with date pattern (2024-01-01) | N/A | `^\d{4}-\d{2}-\d{2}$` | ✅ Use Regex (complex pattern) |
+
+**Guidelines:**
+- **Use Glob Patterns** (`includedPages`/`excludedPages`) for most cases - they're simpler and more readable
+- **Use Regex Patterns** (`excludePatterns`) only when you need advanced matching like character classes, lookaheads, or complex alternations
+
 ## Usage Examples
 
 ### Development Speed Build
@@ -188,19 +296,114 @@ module.exports = withPageFilter(filterConfig)({
 ```
 
 ### Production Admin Exclusion
-Exclude admin and debug pages from production builds:
+Exclude admin and debug pages from production builds using glob patterns:
 
 ```javascript
 const filterConfig = {
   enabled: process.env.NODE_ENV === 'production',
   excludedPages: [
-    'admin',
-    'debug',
-    'dev/tools',
+    'admin/**',        // Exclude all admin routes
+    'debug',           // Exclude debug page
+    'dev/**',          // Exclude all dev tools and utilities
+    '**/test',         // Exclude all test pages
+    'internal/**',     // Exclude internal pages
   ],
-  excludePatterns: [
-    'admin/.*',
-    'dev/.*',
+};
+```
+
+### Multi-team Development
+Build only specific feature sets for different teams:
+
+```javascript
+// Team A: Only marketing pages
+const marketingConfig = {
+  enabled: true,
+  includedPages: [
+    'index',
+    'about',
+    'contact',
+    'blog/**',         // All blog routes
+    'marketing/**',    // All marketing pages
+  ],
+};
+
+// Team B: Only product pages
+const productConfig = {
+  enabled: true,
+  includedPages: [
+    'products/**',     // All product routes
+    'checkout/**',     // All checkout routes
+    'cart',            // Shopping cart
+  ],
+};
+```
+
+### Exclude Test and Debug Routes
+Use glob patterns to exclude testing and debugging routes:
+
+```javascript
+const filterConfig = {
+  enabled: process.env.NODE_ENV === 'production',
+  excludedPages: [
+    '**/*-test',       // Exclude all routes ending with -test
+    '**/*-debug',      // Exclude all routes ending with -debug
+    'test/**',         // Exclude all test directory routes
+    'debug/**',        // Exclude all debug directory routes
+    'dev/**',          // Exclude all development routes
+    'playground/**',   // Exclude playground routes
+  ],
+};
+```
+
+### API Route Filtering
+Filter specific API routes using glob patterns:
+
+```javascript
+const filterConfig = {
+  enabled: true,
+  excludedPages: [
+    'api/internal/**',        // Exclude internal API routes
+    'api/*/admin',            // Exclude admin endpoints in any API version
+    'api/webhooks/test-*',    // Exclude test webhooks
+    'api/v*/deprecated/**',   // Exclude deprecated endpoints in all versions
+  ],
+};
+```
+
+### Feature Flag Based Builds
+Create builds with specific features using glob patterns:
+
+```javascript
+const filterConfig = {
+  enabled: true,
+  includedPages: [
+    'index',                           // Home page
+    'about',                           // About page
+    // Conditionally include features based on environment
+    ...(process.env.ENABLE_BLOG ? ['blog/**'] : []),
+    ...(process.env.ENABLE_SHOP ? ['shop/**', 'cart', 'checkout/**'] : []),
+    ...(process.env.ENABLE_FORUM ? ['forum/**', 'community/**'] : []),
+  ],
+};
+```
+
+### Multi-language Site Filtering
+Build specific language versions:
+
+```javascript
+const filterConfig = {
+  enabled: true,
+  // Only build English version
+  includedPages: [
+    'en/**',           // All English pages
+    'index',           // Root page
+  ],
+  // Or exclude other languages
+  excludedPages: [
+    'fr/**',           // Exclude French
+    'de/**',           // Exclude German  
+    'es/**',           // Exclude Spanish
+    'ja/**',           // Exclude Japanese
   ],
 };
 ```
@@ -251,10 +454,45 @@ npm start
 The plugin works by integrating with Next.js's webpack configuration and build process:
 
 1. **Webpack Plugin Integration**: The plugin hooks into webpack's module resolution process
-2. **Page Detection**: It identifies page files in the `/pages` directory
-3. **Filtering Logic**: Based on your configuration, it determines which pages to exclude
-4. **Module Resolution**: Excluded pages are replaced with empty modules during the build process
-5. **Build Optimization**: The final bundle only includes the pages you want
+2. **Page Detection**: It identifies page files in the `/pages` and `/app` directories (based on router support configuration)
+3. **Path Normalization**: Routes are normalized (lowercase, forward slashes) for consistent matching
+4. **Pattern Matching**: For each page, the plugin checks if it should be filtered using:
+   - **Glob patterns** (via [minimatch](https://github.com/isaacs/minimatch)) - checked first
+   - **Exact string matching** - fallback for backward compatibility
+   - **Regex patterns** (via `excludePatterns`) - for advanced cases
+5. **Filtering Logic**: Based on your configuration, it determines which pages to include/exclude
+6. **Module Replacement**: Filtered pages are replaced with empty modules during the build process
+7. **Build Optimization**: The final bundle only includes meaningful content for pages you want
+
+### Important: Custom 404 Replacement
+
+The plugin **replaces** filtered pages with custom 404 pages rather than **removing** them entirely from the build. This approach:
+
+- ✅ **Clear user feedback**: Users see a "Page Not Available" message if they access a filtered page
+- ✅ **Preserves routing structure**: Pages still exist in the manifest
+- ✅ **Prevents build errors**: No missing module errors from dependencies
+- ✅ **Testable**: Contains a unique marker (`NEXT_BUILD_FILTER_EXCLUDED_PAGE`) for verification
+- ✅ **Proper HTTP status**: Returns 404 status code
+
+**For App Router**: Uses Next.js's built-in `notFound()` function for proper 404 handling
+**For Pages Router**: Returns a custom 404 component with proper status code
+
+**What this means:**
+- Filtered pages will still appear in your `.next/server` directory
+- They will show a "Page Not Available" message if accessed
+- The pages contain minimal code (just the 404 component)
+- Build verification can detect filtered pages via the unique marker
+
+### Pattern Matching Priority
+
+When matching routes, the plugin uses this order:
+
+1. **Glob Pattern Match** (via minimatch): `admin/**` matches `admin/users/list`
+2. **Exact Match**: `admin` matches only `admin`
+3. **Substring Match**: `admin` also matches routes containing `admin` (backward compatibility)
+4. **Regex Match** (if using `excludePatterns`): `admin/.*` matches `admin/anything`
+
+This multi-tiered approach ensures backward compatibility while providing powerful glob pattern support.
 
 ## Project Structure
 
@@ -333,23 +571,228 @@ npm run build:filtered
 4. **Test Thoroughly**: Always test your filtered builds to ensure functionality
 5. **Document Configuration**: Keep your filtering logic well-documented for your team
 
+## Migration Guide
+
+### Migrating from Regex Patterns to Glob Patterns
+
+If you're currently using `excludePatterns` with regex, consider migrating to glob patterns in `excludedPages` for better readability:
+
+**Before (Regex):**
+```javascript
+const filterConfig = {
+  excludePatterns: [
+    'admin/.*',        // Regex
+    'dev/.*',          // Regex
+    '.*test.*',        // Regex
+  ],
+};
+```
+
+**After (Glob):**
+```javascript
+const filterConfig = {
+  excludedPages: [
+    'admin/**',        // Glob - clearer intent
+    'dev/**',          // Glob - easier to read
+    '**/test/**',      // Glob - more intuitive
+  ],
+};
+```
+
+**Note:** Both approaches work! Use glob patterns for simplicity and regex for complex patterns.
+
 ## Troubleshooting
 
 ### Pages Still Appearing in Build
-- Check that `enabled: true` is set in your configuration
-- Verify the page paths match exactly (case-sensitive)
-- Enable verbose logging to see what's being processed
+- ✅ Check that `enabled: true` is set in your configuration
+- ✅ Verify the page paths match (glob patterns are case-sensitive by default)
+- ✅ Enable `verbose: true` to see what's being processed
+- ✅ Test your glob pattern: `admin/**` matches all nested routes, while `admin/*` only matches direct children
+- ✅ Ensure you're running the build with the correct environment variable: `FILTER_PAGES=true npm run build`
+
+### Glob Pattern Not Matching
+
+**Common Issues:**
+1. **Wrong wildcard usage**
+   - ❌ `admin/*` only matches direct children like `/admin/users`
+   - ✅ `admin/**` matches all nested routes like `/admin/users/edit`
+
+2. **Case sensitivity**
+   - Route paths are normalized to lowercase before matching
+   - Pattern: `Admin/**` will be normalized to `admin/**`
+
+3. **Missing or extra slashes**
+   - ✅ Correct: `admin/users/**`, `**/test`, `api/*`
+   - ❌ Avoid: `/admin/users/**` (leading slash not needed)
+
+4. **Not matching what you expect**
+   - Enable `verbose: true` to see the actual route paths
+   - Example verbose output: `📄 Filtering out: admin/users/edit`
+   - Compare the logged path with your pattern
+
+**Testing Your Patterns:**
+
+Use `verbose: true` and check the console output during build:
+```javascript
+const filterConfig = {
+  enabled: true,
+  verbose: true,  // Shows which routes are being filtered
+  excludedPages: ['admin/**'],
+};
+```
+
+Console output will show:
+```
+📄 Filtering out: admin/dashboard
+📄 Filtering out: admin/users/list
+📄 Filtering out: admin/settings/profile
+```
+
+**Pattern Matching Examples:**
+
+| Route Path | Pattern | Matches? | Why |
+|------------|---------|----------|-----|
+| `admin/users` | `admin/*` | ✅ Yes | Direct child |
+| `admin/users/edit` | `admin/*` | ❌ No | Too deeply nested |
+| `admin/users/edit` | `admin/**` | ✅ Yes | `**` matches any depth |
+| `blog/post-123` | `blog/*-*` | ✅ Yes | `*` matches `post` and `123` |
+| `api/v1/users` | `api/*/users` | ✅ Yes | `*` matches `v1` |
+| `api/v1/internal/users` | `api/*/users` | ❌ No | Too many segments |
+| `anything/internal/data` | `**/internal/**` | ✅ Yes | `**` matches any segments |
 
 ### Build Errors
-- Ensure all required pages (like `_app.js`, `_document.js`) are not being filtered
+- Ensure all required pages (like `_app.js`, `_document.js`, `_app.tsx`) are not being filtered
 - Check that your regex patterns are valid if using `excludePatterns`
+- Avoid overly broad patterns that might exclude critical Next.js files
+- Test patterns incrementally: start with one pattern and add more once working
 
 ### Development vs Production Differences
 - Set `enableInDev: true` if you want consistent behavior across environments
 - Use environment variables to control filtering per environment
+- Note: By default, filtering is disabled in development mode unless `enableInDev` is set
+- Remember: `npm run dev` vs `npm run build` behave differently by default
+
+### Advanced Debugging
+
+If you're having trouble with patterns, try these steps:
+
+1. **Start simple**: Test with an exact match first
+```javascript
+excludedPages: ['admin']  // Start with exact match
+```
+
+2. **Add verbosity**: See what's being matched
+```javascript
+verbose: true
+```
+
+3. **Test one pattern at a time**: Isolate the problematic pattern
+```javascript
+excludedPages: ['admin/**']  // Test one at a time
+```
+
+4. **Check the actual route paths**: Look at your project structure
+```
+pages/
+  admin/
+    users.js        → Route path: admin/users
+    settings/
+      profile.js    → Route path: admin/settings/profile
+```
+
+5. **Use the demos**: Test your patterns in the included demo projects
+```bash
+cd demo/pages-router-demo
+FILTER_PAGES=true npm run build
+```
+
+## Technical Details
+
+### Glob Pattern Matching Library
+
+This plugin uses [minimatch](https://github.com/isaacs/minimatch) for glob pattern matching, the same library used by many popular tools like:
+- npm
+- webpack
+- babel
+- eslint
+
+Minimatch provides powerful and reliable glob pattern matching with full support for:
+- Brace expansion: `{a,b,c}`
+- Extended glob patterns: `@(pattern|list)`
+- Multiple wildcards: `**/**/`
+- Character classes: `[abc]`, `[0-9]`
+
+### Performance Considerations
+
+- Glob pattern matching is performed during the webpack build phase
+- Pattern matching is highly optimized by minimatch
+- Routes are normalized once and cached for efficient matching
+- Only page/route files are checked (not all webpack modules)
+
+### Compatibility
+
+- ✅ Next.js 12+ (Pages Router)
+- ✅ Next.js 13+ (App Router)
+- ✅ Node.js 16+
+- ✅ Works with TypeScript
+- ✅ Compatible with all Next.js deployment targets (standalone, static export, etc.)
+
+## Testing
+
+This project includes a comprehensive test suite with unit tests and end-to-end tests.
+
+### Running Tests
+
+```bash
+# Run all unit tests
+npm test
+
+# Run unit tests in watch mode (for development)
+npm run test:watch
+
+# Run unit tests with coverage report
+npm run test:coverage
+
+# Run end-to-end tests (actual builds)
+npm run test:e2e
+
+# Run all tests (unit + e2e)
+npm run test:all
+```
+
+### Test Structure
+
+- **Unit Tests** (`tests/unit/`): Test core functionality using Vitest
+  - `glob-patterns.test.js`: Tests for glob pattern matching
+  - `plugin.test.js`: Tests for plugin core functionality
+  - `with-page-filter.test.js`: Tests for configuration wrapper
+
+- **E2E Tests** (`tests/e2e/`): Test actual Next.js builds
+  - Verifies filtering works correctly in real builds
+  - Tests both Pages Router and App Router demos
+
+### Test Coverage
+
+The test suite covers:
+- ✅ Glob pattern matching with various patterns
+- ✅ Path normalization and route extraction
+- ✅ Page file identification (Pages Router & App Router)
+- ✅ Filtering logic (includedPages, excludedPages, patterns)
+- ✅ Configuration options and defaults
+- ✅ Webpack integration
+- ✅ Actual build output verification
+
+See `tests/README.md` for detailed testing documentation.
 
 ## Contributing
 
+Contributions are welcome! When contributing:
+
+1. Write tests for new features
+2. Ensure all tests pass: `npm run test:all`
+3. Update documentation as needed
+4. Submit a pull request
+
 Feel free to submit issues, feature requests, or pull requests to improve this plugin.
 
 ## License

package/index.d.ts

@@ -11,13 +11,24 @@ declare module 'next-build-filter' {
     /** Apply filtering in development mode */
     enableInDev?: boolean;
     
-    /** Pages to include (if specified, only these will be built) */
+    /** 
+     * Pages to include (if specified, only these will be built)
+     * Supports glob patterns: 'admin/**', 'blog/*', '*\/test'
+     * @example ['index', 'about', 'blog/**', 'products/*']
+     */
     includedPages?: string[];
     
-    /** Pages to exclude from build */
+    /** 
+     * Pages to exclude from build
+     * Supports glob patterns: 'admin/**', 'dev/*', '*\/internal'
+     * @example ['admin/**', 'dev/**', '*\/test']
+     */
     excludedPages?: string[];
     
-    /** Regex patterns for page exclusion */
+    /** 
+     * Regex patterns for advanced page exclusion
+     * @example ['dev/.*', '.*admin.*', '^api/v[0-9]+/']
+     */
     excludePatterns?: string[];
     
     /** Pages directory name (default: 'pages') */

package/lib/empty-module.js

@@ -1,29 +1,94 @@
-// Empty module to replace filtered pages
-// This module provides a default export that's compatible with both Pages Router and App Router
+/**
+ * Empty module to replace filtered pages
+ * 
+ * This module provides a custom 404 response with a detectable marker
+ * that can be verified in tests and provides clear feedback to users.
+ * 
+ * Marker: NEXT_BUILD_FILTER_EXCLUDED_PAGE
+ */
 
-function EmptyPage() {
-  return null;
+// Try to import notFound for App Router (will fail gracefully for Pages Router)
+let notFound;
+try {
+  notFound = require('next/navigation').notFound;
+} catch (e) {
+  // Not in App Router context or Next.js not available
+  notFound = null;
 }
 
-// For React components (Pages Router)
-module.exports = EmptyPage;
-module.exports.default = EmptyPage;
+// Marker string to identify filtered pages
+const FILTER_MARKER = 'NEXT_BUILD_FILTER_EXCLUDED_PAGE';
 
-// For App Router (ES6 export)
-if (typeof exports !== 'undefined') {
-  exports.default = EmptyPage;
+// For Pages Router: Return a component that renders 404
+function FilteredPage() {
+  // If we're in App Router and notFound is available, use it
+  if (notFound && typeof notFound === 'function') {
+    notFound();
+    return null; // notFound() throws, so this won't be reached
+  }
+  
+  // For Pages Router or fallback: Return a custom 404 component
+  // Using React.createElement to avoid JSX
+  const React = require('react');
+  return React.createElement(
+    'div',
+    {
+      style: {
+        display: 'flex',
+        flexDirection: 'column',
+        alignItems: 'center',
+        justifyContent: 'center',
+        minHeight: '100vh',
+        fontFamily: 'system-ui, -apple-system, sans-serif',
+        backgroundColor: '#f5f5f5',
+      },
+      'data-filter-marker': FILTER_MARKER
+    },
+    [
+      React.createElement('h1', { key: 'title', style: { fontSize: '3rem', margin: '0' } }, '404'),
+      React.createElement(
+        'p',
+        { key: 'message', style: { fontSize: '1.2rem', color: '#666', marginTop: '1rem' } },
+        'Page Not Available'
+      ),
+      React.createElement(
+        'p',
+        { key: 'detail', style: { fontSize: '0.9rem', color: '#999', marginTop: '0.5rem' } },
+        'This page has been filtered out during build.'
+      ),
+      React.createElement(
+        'div',
+        { key: 'marker', style: { display: 'none' } },
+        FILTER_MARKER
+      ),
+    ]
+  );
 }
 
+// Set status code for Pages Router
+FilteredPage.getInitialProps = ({ res }) => {
+  if (res) {
+    res.statusCode = 404;
+  }
+  return {};
+};
+
+// For React components (Pages Router)
+module.exports = FilteredPage;
+module.exports.default = FilteredPage;
+
+// Export the marker for testing
+module.exports.FILTER_MARKER = FILTER_MARKER;
+
 // Generate metadata for App Router if needed
 module.exports.generateMetadata = () => ({
-  title: 'Page Not Available',
-  description: 'This page has been filtered out during build'
+  title: 'Page Not Available - 404',
+  description: 'This page has been filtered out during build',
 });
 
 // Generate static params for dynamic routes if needed
 module.exports.generateStaticParams = () => [];
 
-// Export all common App Router functions as empty
+// Export all common App Router functions
 module.exports.generateViewport = () => ({});
-module.exports.generateStaticParams = () => [];
 module.exports.revalidate = false;

package/lib/next-build-filter-plugin.js

@@ -1,11 +1,13 @@
 const path = require('path');
 const fs = require('fs');
+const { minimatch } = require('minimatch');
 
 /**
  * Next.js Build Filter Plugin
  * 
  * This plugin allows you to exclude specific pages from the build process
  * without actually removing the files from your project.
+ * Supports glob patterns via minimatch for flexible filtering.
  */
 class NextBuildFilterPlugin {
   constructor(options = {}) {
@@ -64,11 +66,13 @@ class NextBuildFilterPlugin {
         
         // Check if this is a page file
         if (this.isPageFile(request, resolveData.context)) {
+          const normalizedRequest = this.normalizePath(request);
+          const routePath = this.extractRoutePath(normalizedRequest);
           const shouldExclude = this.shouldExcludePage(request);
           
           if (shouldExclude) {
             if (this.options.verbose) {
-              console.log(`📄 NextBuildFilterPlugin: Replacing page with empty module: ${request}`);
+              console.log(`📄 Filtering out: ${routePath || request}`);
             }
             
             // Replace with empty module instead of blocking the request
@@ -152,6 +156,7 @@ class NextBuildFilterPlugin {
 
   /**
    * Determine if a page should be excluded from the build
+   * Supports glob patterns, exact matches, and regex patterns
    */
   shouldExcludePage(request) {
     const normalizedRequest = this.normalizePath(request);
@@ -164,6 +169,11 @@ class NextBuildFilterPlugin {
     if (this.options.includedPages.length > 0) {
       const isIncluded = this.options.includedPages.some(page => {
         const normalizedPage = this.normalizePath(page);
+        // Try glob matching first (using minimatch)
+        if (minimatch(routePath, normalizedPage)) {
+          return true;
+        }
+        // Fallback to exact match or prefix match for backward compatibility
         return routePath === normalizedPage || routePath.startsWith(normalizedPage + '/');
       });
       return !isIncluded;
@@ -173,12 +183,17 @@ class NextBuildFilterPlugin {
     if (this.options.excludedPages.length > 0) {
       const isExcluded = this.options.excludedPages.some(page => {
         const normalizedPage = this.normalizePath(page);
+        // Try glob matching first (using minimatch)
+        if (minimatch(routePath, normalizedPage)) {
+          return true;
+        }
+        // Fallback to exact match or prefix match for backward compatibility
         return routePath === normalizedPage || routePath.startsWith(normalizedPage + '/');
       });
       if (isExcluded) return true;
     }
     
-    // Check exclude patterns
+    // Check exclude patterns (regex patterns)
     if (this.options.excludePatterns.length > 0) {
       const isPatternExcluded = this.options.excludePatterns.some(pattern => {
         try {
@@ -227,8 +242,8 @@ class NextBuildFilterPlugin {
     
     // Remove file name and extension for App Router
     if (this.options.supportAppRouter && normalizedRequest.includes(`/${this.options.appDir}/`)) {
-      // Remove /page.tsx, /page.js, etc.
-      routePath = routePath.replace(/\/page\.(tsx|ts|jsx|js)$/, '');
+      // Remove /page.tsx, /page.js, etc. (with or without leading slash)
+      routePath = routePath.replace(/\/?page\.(tsx|ts|jsx|js)$/, '');
       // Remove leading slash if present
       routePath = routePath.replace(/^\//, '');
     } else {

package/lib/with-page-filter.js

@@ -1,9 +1,11 @@
 const path = require('path');
+const { minimatch } = require('minimatch');
 
 /**
  * Next.js Page Filter Plugin
  * 
  * Enhanced version that supports both Pages Router and App Router (Next.js 13+)
+ * Supports glob patterns for includedPages and excludedPages options
  */
 function withPageFilter(options = {}) {
   return (nextConfig = {}) => {
@@ -91,6 +93,11 @@ function shouldExcludePage(request, options) {
   if (options.includedPages && options.includedPages.length > 0) {
     const isIncluded = options.includedPages.some(page => {
       const normalizedPage = normalizePath(page);
+      // Try glob matching first
+      if (minimatch(routePath, normalizedPage)) {
+        return true;
+      }
+      // Fallback to exact match or substring match for backward compatibility
       return routePath === normalizedPage || routePath.includes(normalizedPage);
     });
     return !isIncluded;
@@ -100,12 +107,17 @@ function shouldExcludePage(request, options) {
   if (options.excludedPages && options.excludedPages.length > 0) {
     const isExcluded = options.excludedPages.some(page => {
       const normalizedPage = normalizePath(page);
+      // Try glob matching first
+      if (minimatch(routePath, normalizedPage)) {
+        return true;
+      }
+      // Fallback to exact match or substring match for backward compatibility
       return routePath === normalizedPage || routePath.includes(normalizedPage);
     });
     if (isExcluded) return true;
   }
   
-  // Check exclude patterns
+  // Check exclude patterns (regex patterns)
   if (options.excludePatterns && options.excludePatterns.length > 0) {
     const isPatternExcluded = options.excludePatterns.some(pattern => {
       try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "next-build-filter",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "A Next.js plugin to exclude pages/routes during build without removing files. Supports both Pages Router and App Router (Next.js 13+).",
   "main": "index.js",
   "types": "index.d.ts",
@@ -11,8 +11,13 @@
     "README.md"
   ],
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:e2e": "node tests/e2e/run-e2e-tests.js",
+    "test:all": "npm run test && npm run test:e2e",
     "prepublishOnly": "npm run build",
+    "postversion": "npm publish",
     "build": "echo \"No build process needed for now\""
   },
   "keywords": [
@@ -26,26 +31,34 @@
     "app-router",
     "pages-router",
     "optimization",
-    "bundle"
+    "bundle",
+    "glob",
+    "pattern-matching",
+    "wildcard"
   ],
-  "author": "",
+  "author": "banyudu <banyudu@gmail.com>",
   "license": "MIT",
   "peerDependencies": {
     "next": ">=12.0.0",
     "react": ">=17.0.0"
   },
+  "dependencies": {
+    "minimatch": "^9.0.0"
+  },
   "devDependencies": {
-    "@types/node": "^20.0.0"
+    "@types/node": "^20.0.0",
+    "@vitest/coverage-v8": "^1.0.0",
+    "vitest": "^1.0.0"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/your-username/next-build-filter.git"
+    "url": "git+https://github.com/banyudu/next-build-filter.git"
   },
   "bugs": {
-    "url": "https://github.com/your-username/next-build-filter/issues"
+    "url": "https://github.com/banyudu/next-build-filter/issues"
   },
-  "homepage": "https://github.com/your-username/next-build-filter#readme",
+  "homepage": "https://github.com/banyudu/next-build-filter#readme",
   "engines": {
-    "node": ">=16.0.0"
+    "node": ">=18.0.0"
   }
-}
+}