Two Routing Modes

@keenmate/svelte-spa-router supports two routing modes: Hash Mode and History Mode. Each has its own advantages and use cases.

Hash Mode (Default)

Hash mode uses the URL hash fragment for routing. URLs look like http://example.com/#/about. The hash portion (#/about) is handled client-side and never sent to the server.

Advantages

  • No server configuration: Works out of the box
  • Static hosting friendly: Perfect for GitHub Pages, Netlify, etc.
  • Local development: Works with file:// protocol
  • Simple deployment: No special server rules needed

Disadvantages

  • URLs have #: Less aesthetically pleasing
  • SEO concerns: Though modern search engines handle it
  • Link behavior: Ctrl+Click and target attribute don't work as expected

Configuration

Hash mode is the default - no configuration needed!

Hash mode (default) 
 
 
App.svelte 
 
 
 
Example URLs in Hash Mode
 
  • http://localhost:5054/#/ - Home
    •  
  • http://localhost:5054/#/about - About page
    •  
  • http://localhost:5054/#/user/123 - User profile
    •  
  • http://localhost:5054/#/products?search=laptop - Products with query
 
🔗 View Hash Mode Example
 
History Mode
 
History mode uses the HTML5 History API for clean URLs like http://example.com/about.
				This provides a better user experience but requires server configuration.
 
Advantages
 
  • Clean URLs: No hash symbol in URLs
    •  
  • Better SEO: Search engines prefer clean URLs
    •  
  • Better UX: More professional appearance
    •  
  • Link behavior: Ctrl+Click and target attributes work correctly
 
Disadvantages
 
  • Server configuration required: Must serve index.html for all routes
    •  
  • Deployment complexity: Needs proper server setup
    •  
  • No file:// support: Doesn't work with local files
 
Configuration
 
Enable history mode in your main.js before mounting the app:
 
History mode configuration 
 
 
 
Example URLs in History Mode
 
  • http://localhost:5050/ - Home
    •  
  • http://localhost:5050/about - About page
    •  
  • http://localhost:5050/user/123 - User profile
    •  
  • http://localhost:5050/products?search=laptop - Products with query
 
🚀 View History Mode Example
 
Server Configuration for History Mode
 
For history mode to work, your server must serve index.html for all routes.
				This is because the client-side router needs to handle the routing, not the server.
 
Nginx
 
nginx.conf 
 
 
 
Apache
 
.htaccess 
 
 
 
Express.js
 
server.js 
 
 
 
Vite Development Server
 
Vite handles this automatically in development mode. For production, configure your hosting provider.
 
vite.config.js 
 
 
 
Base Path Configuration
 
If your app is served from a subdirectory (e.g., http://example.com/app/),
				you need to configure the base path.
 
Base path configuration 
 
 
 
Important: Make sure the base path in your router configuration matches
				the base path in your build tool configuration (Vite, webpack, etc.).
 
Which Mode Should I Use?
 
Use Hash Mode When:
 
  • Deploying to static hosting (GitHub Pages, Netlify, S3)
    •  
  • You don't have control over server configuration
    •  
  • You need to support file:// protocol
    •  
  • You want zero-configuration deployment
    •  
  • SEO is not a primary concern
 
Use History Mode When:
 
  • You have control over server configuration
    •  
  • Clean URLs are important for your application
    •  
  • SEO is important
    •  
  • You want the best user experience
    •  
  • You're deploying to platforms that support SPA routing (Vercel, Netlify)
 
Switching Between Modes
 
You can easily switch between modes by changing a single line in your main.js.
				The rest of your application code remains unchanged!
 
Switching modes 
 
 
 
Pro Tip: You can use environment variables to automatically choose the mode: 
Environment-based configuration