newtab

thenewtab.app

A minimal, customizable new-tab homepage built with React and TypeScript. Configuration is stored in the browser's localStorage and is fully editable from a built-in settings page. On first load, a default config.json is used to seed the initial config.

Installation

docker run -d \
  -p 3541:3541 \
  tastinggrounds/newtab

Then open http://localhost:3541. All configuration is managed from the built-in settings page.

Development

npm install
npm run dev

Open http://localhost:3542 in your browser. Use the settings page to customize, or edit public/config.json to change the default seed config.

To simulate the hosted environment (as deployed to thenewtab.app):

VITE_HOSTED=true npm run dev

This enables hosted-only features like the attribution footer.

Testing

npm run test          # run tests once
npm run test:watch    # run tests in watch mode

Configuration

All configuration is managed from the built-in settings page, which has two tabs:

• Background — configure background image, overlay color, opacity, and gradient
• Links — add, remove, rename, and reorder sections and links

Configuration is stored in the browser's localStorage. On first load, a default config.json seeds the initial config. You can also import/export the full config as a base64 string from the settings header.

For the full config file schema and examples, see docs/config-file.md.

Docker

Build and run with Docker:

docker build -f docker/Dockerfile -t newtab .

docker run -d \
  -p 3541:3541 \
  newtab

Then open http://localhost:3541.

Loading config via volume mount

You can optionally provide an initial config.json by volume-mounting it into the container. This is useful for seeding the config on first load or sharing the same config across multiple instances:

docker run -d \
  -p 3541:3541 \
  -v /path/to/your/config.json:/usr/share/nginx/html/config.json:ro \
  newtab

The volume-mounted config is used as the initial config on first load. Once the config is persisted to localStorage, the local copy takes precedence. You can also use the import/export feature in settings to transfer configs between browsers.

Browser New Tab

To use this as your browser's new tab page, install the Custom New Tab URL extension (Chrome/Edge) and point it to where you're hosting the app.