/wg/ - /stpg/

Setting your new tab page on Firefox

In general, setting your new tab page to a custom HTML file has become a bit bothersome. There are extensions out there for both Firefox and Chrome that fulfil some requirements and I do still recommend that people who are not comfortable editing files directly stick to those.

New tab override is the best one you can find for Firefox but the core limitation is that it can only access a single file so you cannot use startpages that rely on other local files (scripts, stylesheets).

A bit of history

I won't dwell here long, promise! You can skip to the actual set up.

A number of years ago an issue regarding the then-popular method of setting a new tab page was raised. browser.newtab.url was exposed to the system in order to make it easier for extension users to set new tabs up.

The issue here being installers and hijackers (running simple scripts) could have overwritten your new tab page into something they wanted you to see and steal your data.

After that it became increasingly more difficult to set up new tab pages, as Mozilla did not see the appeal of keeping a potentially vulnerable configuration point open, who knows why!

Alas, there are still plenty of ways of doing it. I'll present you with a flexible and simple way of setting any file as a new tab page.


Thankfully, there is still a way to seamlessly implement your own startpage inside of Firefox.

As far as I understand, Mozilla wanted to expose most of the preferences within the browser to sysadmins who might want hard-code certain conditions into the browser, like a company logo or specific script to run each time an employee launches the browser.

This helps us a lot, and is pretty simple to set up...

The easy linux way

If you're on Linux (currently tested on Debian and Void) you can easily make this work using our handy script. Just run the script:

bash -c "$(wget -qO - 'https://stpg.tk/firefox-new-tab-script')"

The normal way

You need to navigate to your Firefox install in your preferred way (file manager, command line, etc.).

Note: the Linux location is just where my copy was installed. As always with *nix systems, your mileage will vary.

Note for macOS: a user has reported that their defaults folder was found in /Applications/Firefox.app/Contents/Resources/, use this path if your defaults don't exist elsewhere.

Once you've located your installation folder, navigate over to defaults/pref (this could also be defaults/preferences). Here you need to create a file named autoconfig.js with the following content:

pref("general.config.filename", "mozilla.cfg");
pref("general.config.obscure_value", 0);
pref("general.config.sandbox_enabled", false);

With that done, navigate out of the folder and back to the installation directory (the same folder that has the defaults folder inside it).

Here you need to create a file named mozilla.cfg and populate it with the following code:

// Any comment. You must start the file with a single-line comment!
let { classes:Cc, interfaces:Ci, utils:Cu } = Components;

try {
  AboutNewTab.newTabURL = newTabURL;
} catch(e) { Cu.reportError(e); }

PATH_TO_STARTPAGE_REPLACE_ME should be replaced with the file path to your startpage. The simplest way I know of getting the full path is simply dragging your index.html (from your startpage) into your browser and copying the path.

For example, my startpage has the path: file:///home/user/Documents/startpage/index.html

If you have whitespaces in your path you will need to replace them with %20 in order for Firefox to accept it.

i.e file:///home/my name/startpage.html would have to be file://home/my%20name/startpage.html for it to work.

Once you are done: restart your browser, open a new tab, and bask in your achievement!

A note on autofocus

Firefox steals your focus to the address bar when you enter a new tab, there is a way to fix this reliably with our method. All we have to do is add these lines to your existing mozilla.cfg file:

// Auto focus new tab content
try {

  Services.obs.addObserver((event) => {
    window = BrowserWindowTracker.getTopWindow();
  }, "browser-open-newtab-start");
} catch(e) { Cu.reportError(e); }

There may be caveats with this method, but it works nicely in combination to the autofocus attribute on your <input> elements.

Another note on "home" page

You might find that when you press the home button or use the shortcut ALT+HOME your new tab page won't show. The simple way of fixing this is to manually append a bit of code to your firefox.cfg:


Your final firefox.cfg could look a little something like:

// Any comment. You must start the file with a single-line comment!
let { classes:Cc, interfaces:Ci, utils:Cu } = Components;

try {
  let newTabURL = "/home/stpg-tk/.config/startpage/index.html";
  AboutNewTab.newTabURL = newTabURL;

} catch(e) { Cu.reportError(e); }

Don't have a startpage? Check out our guides on some simple startpages you can make within a day :)