A self-hosted, customizable and ad-free Google Search experience.
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.
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 | |
---|---|---|
➡️ |
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.
Homepage | Search results |
---|---|
Engine manager | Engine selector |
---|---|
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.
- Some technical knowledge - I'll walk you through it in this guide. If you don't already have them, you'll need NodeJS v18 or higher and yarn package manager.
- A Google Developer API key with Custom Search API privileges - You can do this directly on the Programmable Search Engine overview page or manually on your Google Cloud credentials page.
- At least one custom search engine configured in the Google account's
Programmable Search Engine console -
Your console should look something like this:
From a terminal window, run the following commands:
$ git clone https://github.com/dan-lovelace/giggle.git
$ cd giggle
$ yarn initialize
-
Clone this repository to your current directory
git clone https://github.com/dan-lovelace/giggle.git
-
Change into the newly-created directory
cd giggle
-
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
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
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.
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.
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 |
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.
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.
The following commands will build your project and start it:
$ yarn build
$ yarn start
Read the Next.js Deploying guide for deployment options.