URL Path based navigation for Flutter Web app

Recently I moved one of my flutter app to web. It was working fine when I started from my main url. It was hash driven. But as soon as I started providing direct urls, the web app started showing 404 errors. In this article we will solve this issue by configuring our app for path driven URL Strategies.

Types of URL Navigations for Flutter Web

Flutter web apps support two ways of configuring URL-based navigation on the web:

Hash (default)

Paths are read and written to the hash fragment. For example, flutterexample.dev/#/path/to/screen.

Path

Paths are read and written without a hash. For example, flutterexample.dev/path/to/screen.

Configuring the URL strategy

To configure Flutter to use the path instead, use the setUrlStrategy function provided by the flutter_web_plugins library in the SDK.

The setUrlStrategy API can only be called on the web. The following instructions show how to use a conditional import to call this function on the web, but not on other platforms.

Note: By default, Flutter uses the hash (/#/) location strategy. These instructions are only required if you want to use the URL path strategy.

Web Plugin setup

First, add flutter_web_plugins to your pubspec.yaml:

dependencies:
  flutter_web_plugins:
    sdk: flutter

Then call setUrlStrategy before runApp():

import 'package:flutter/material.dart';
import 'package:flutter_web_plugins/flutter_web_plugins.dart';

void main() {
  setUrlStrategy(PathUrlStrategy());
  runApp(MyApp());
}

#Cross Platform setup

If your app is cross-platform, use Dart’s conditional imports feature by creating three files:

url_strategy.dart

export 'url_strategy_noop.dart' if (dart.library.html) 'url_strategy_web.dart';

url_strategy_noop.dart

void usePathUrlStrategy() {
  // noop
}

url_strategy_web.dart

import 'package:flutter_web_plugins/flutter_web_plugins.dart';

void usePathUrlStrategy() {
  setUrlStrategy(PathUrlStrategy());
}

Then, call setPathUrlStrategy before runApp():

main.dart

import 'package:flutter/material.dart';
import 'url_strategy.dart';

void main() {
  usePathUrlStrategy();
  runApp(MyApp());
}

Using conditional imports ensures that the flutter_web_plugins library is only loaded when your app is running on the web.

Configuring your web server

The local dev server created by running flutter run -d chrome is configured to handle any path gracefully and fallback to your app’s index.html file.

To configure your web server to support PathUrlStrategy you will need add some rewrite rules to your htaccess file.

.htaccess

RewriteEngine On
# set the base URL prefix
RewriteBase /
# for requests for index.html, just respond with the file
RewriteRule ^index.html$ - [L]
# if requested path is not a valid filename, continue rewrite
RewriteCond %{REQUEST_FILENAME} !-f
# if requested path is not a valid directory, continue rewrite
RewriteCond %{REQUEST_FILENAME} !-d
# if you have continue to here, respond with index.html
RewriteRule . /index.html [L]

Whats Next

In this article I have given your the minimal steps required to configure your web app and the web server for URL Path based navigation. We can extend it as per our requirement so that it can even support forward and backward in browsers. Please share how you implemented URL strategies in your flutter web app.

Reference: docs.flutter.dev/development/ui/navigation/..

Did you find this article valuable?

Support Neeraj Jaiswal by becoming a sponsor. Any amount is appreciated!