/giggle

A self-hosted, customizable and ad-free Google Search experience

Primary LanguageTypeScriptMIT LicenseMIT

Giggle

A self-hosted, customizable and ad-free Google Search experience.

Table of contents

  1. Introduction
  2. Getting started
  3. Development
  4. Building & deployment

Introduction

Giggle lets you run Google searches against allow- and block-lists in an easy way. You create lists of sites to include or exclude in Google's Programmable Search Engine service and Giggle provides an interface for them.

How it works

Giggle works by making requests to Google's Custom Search JSON API using your Developer API key. After creating one or more Programmable Search Engines in the Google console, you'll add them to Giggle using the engine manager.

1. Google console 2. Giggle engine manager
CSE console ➡️ Engine manager

Different engines may be selected when searching so you can easily switch between them. Giggle also offers the option to use the Site Restricted JSON API which offers unlimited free searches. Be sure to read the JSON API guide so you know what to expect around usage and pricing. If you cannot use the Site Restricted API, you still get 100 searches per day for free.

How it looks

Homepage Search results
Homepage Search results
Engine manager Engine selector
Engine manager Engine selector

Getting started

Giggle is self-hosted meaning you may host it any way you like or just run it locally. It uses Next.js so development and deployment are super easy.

What you'll need

Initialize project

From a terminal window, run the following commands:

$ git clone https://github.com/dan-lovelace/giggle.git
$ cd giggle
$ yarn initialize

Command breakdown

  1. Clone this repository to your current directory

    git clone https://github.com/dan-lovelace/giggle.git
  2. Change into the newly-created directory

    cd giggle
  3. Initialize the project

    yarn initialize

    Initialization does a number of things behind the scenes to get your project in a usable state:

    • Installs Node dependencies
    • Creates a SQLite database and runs migrations to define its schema
    • Creates an environment file where you'll add your Developer API key and any other configurations

Add API key

The initilization script creates a .env file in your app package directory: packages/app/.env. Copy your Developer API key and paste it into the .env file in the right place. The final version should look something like this:

GOOGLE_API_KEY=ABCdef123_gG-aBcDeF123aBcDeF123

Start server

Once your Google API key is in place, run the following command to start the development server:

yarn dev

Note: This will start a local instance without API caching which may run up your search request limits rather quickly if you aren't using the Site Restricted JSON API. There is a MOCK=true environment variable you may set in your packages/app/.env that will return mocked search results when searching instead of hitting the Google API.

Development

Giggle uses Yarn workspaces to manage dependencies. Individual packages are found in the packages directory and you can run commands against a specific one using its name like this:

yarn workspace @giggle/app add lodash

Check out the Next.js documentation for developing with Next.

Environment variables

A number of environment variables are available to configure the application:

Variable Type Default Description
MOCK boolean false Whether search result mocking is enabled
NODE_ENV string development The target environment
RESULTS_CACHE_LENGTH_SECONDS string 3600 How long to cache search results

Databases

If you choose to deploy your application to a real server, you'll need to configure a database other than the one that was automatically created during project initialization. Giggle uses Knex.js to manage database connections and migrations. Open the file packages/db/knexfile.ts to edit configuration for your desired environment. You should set a NODE_ENV environment variable to target a specific environment; Giggle will use development by default.

Testing

Tests are written using Cypress and can be run with either of these commands:

  • yarn workspace @giggle/app cypress:open - Opens a Cypress runner for testing individual spec files.
  • yarn workspace @giggle/app cypress:run - Executes all tests in series.

Building & deployment

The following commands will build your project and start it:

$ yarn build
$ yarn start

Read the Next.js Deploying guide for deployment options.