Freetar - Next.js

An open-source alternative frontend to Ultimate Guitar, built with Next.js.

Features

• 🎸 Search guitar tabs and chords from Ultimate Guitar
• 🎨 Clean, ad-free interface with no popups or distractions
• 📜 Auto-scroll for hands-free reading while playing
• 🎵 Transpose chords to any key (-11 to +11 semitones)
• ⭐ Save favorites locally (no account needed) or to the cloud (sign in)
• 📋 Setlists — create and manage song setlists (requires account)
• 🌓 Dark mode support with system preference detection
• 🖨️ Print-friendly formatting
• 🎯 Chord diagrams with fingering positions
• 📱 Responsive design works on mobile and desktop
• 📝 ChordPro format support - view, export, and copy in standard ChordPro notation
• 📲 Progressive Web App (PWA) - Install on mobile/desktop for offline access and app-like experience

Tech Stack

• Framework: Next.js 14 (App Router)
• Language: TypeScript
• UI: React 18, Tailwind CSS, DaisyUI
• Data Fetching: Axios, Cheerio (web scraping)
• Database: Airtable
• Authentication: NextAuth.js v4 (email + password)
• Deployment: Vercel/Node.js

Getting Started

Prerequisites

• Node.js 22.0.0 or higher
• npm

Installation

1. Clone the repository and install dependencies:

cd freetar-nextjs
npm install

2. Copy the example environment file and fill in your values:

cp .env.example .env.local   # or create .env.local manually

3. Run the development server:

npm run dev

4. Open http://localhost:3000 in your browser.

The app works without any configuration for anonymous users (search, view tabs, localStorage favorites). To enable cloud sync and setlists, complete the Airtable setup below.

---

Airtable Setup (optional — enables accounts, cloud favorites, setlists)

1. Create an Airtable base

Go to airtable.com and create a new base. Then create these 5 tables with the exact names and field types shown:

Table: Users

Field	Type
Email	Single line text (primary field — rename the default "Name" field)
PasswordHash	Single line text
CreatedAt	Single line text

Table: Tabs

Field	Type
TabUrl	Single line text (primary field)
ArtistName	Single line text
SongName	Single line text
Type	Single line text
Version	Number
Votes	Number
Rating	Number
Difficulty	Single line text
Tuning	Single line text
Capo	Number
TabContent	Long text
Chords	Long text
FingersForStrings	Long text
Alternatives	Long text
CreatedAt	Single line text

Table: Favorites

Field	Type
UserId	Single line text (primary field)
TabId	Single line text
CreatedAt	Single line text

Table: Setlists

Field	Type
UserId	Single line text (primary field)
Name	Single line text
Description	Long text
ShareToken	Single line text
CreatedAt	Single line text
UpdatedAt	Single line text

Table: SetlistItems

Field	Type
SetlistId	Single line text (primary field)
TabId	Single line text
Position	Number
Notes	Long text
Transpose	Number
Capo	Number
CreatedAt	Single line text

Note: Use Single line text (not "Link to another record") for all ID fields. Table and field names are case-sensitive.

2. Get your credentials

• API Key: airtable.com/account → Personal Access Tokens → Create token
  • Scopes needed: data.records:read, data.records:write
• Base ID: Open your base in Airtable → Help → API documentation — the Base ID starts with app

3. Configure environment variables

Add to .env.local:

AIRTABLE_API_KEY=pat...
AIRTABLE_BASE_ID=app...
NEXTAUTH_SECRET=<run: openssl rand -base64 32>
NEXTAUTH_URL=http://localhost:3000
NEXT_PUBLIC_NEXTAUTH_ENABLED=true

4. Create user accounts

Users are added directly in the Airtable Users table. Generate a bcrypt hash for their password:

node -e "require('bcryptjs').hash('their-password', 12).then(console.log)"

Then create a record with their Email and the generated hash as PasswordHash.

Project Structure

freetar-nextjs/
├── src/
│   ├── app/                    # Next.js App Router pages
│   │   ├── api/               # API routes
│   │   │   ├── search/        # Search API endpoint
│   │   │   └── tab/           # Tab data API endpoint
│   │   ├── search/            # Search results page
│   │   ├── tab/               # Tab display page
│   │   ├── about/             # About page
│   │   ├── layout.tsx         # Root layout
│   │   ├── page.tsx           # Home page (favorites)
│   │   └── globals.css        # Global styles
│   ├── components/            # React components
│   │   ├── Navbar.tsx         # Navigation bar with search
│   │   ├── SearchResults.tsx  # Search results table
│   │   ├── TabDisplay.tsx     # Tab display with controls
│   │   └── ChordDiagram.tsx   # Chord fingering visualization
│   ├── lib/                   # Utility libraries
│   │   └── ug.ts              # Ultimate Guitar scraping logic
│   └── types/                 # TypeScript type definitions
│       └── index.ts           # Shared types
├── public/                    # Static assets
│   ├── guitar.png            # Logo/favicon source
│   ├── manifest.json         # PWA manifest file
│   ├── icon-*.png            # PWA icons (8 sizes)
│   └── sw.js                 # Service worker (generated)
├── package.json              # Dependencies and scripts
├── tsconfig.json             # TypeScript configuration
├── next.config.js            # Next.js configuration
└── README.md                 # This file

Usage

Searching for Tabs

1. Enter a song name or artist in the search bar
2. Click the search button or press Enter
3. Browse results and click on a tab to view it

Viewing Tabs

• Auto-scroll: Toggle the autoscroll switch and adjust speed with ❮❮ and ❯❯
• Transpose: Use ↑ and ↓ to change the key, click the displayed value to reset
• Show chords: Toggle chord diagrams with fingering positions
• Favorites: Click the ★ to save/remove from favorites
• ChordPro View: Switch between HTML and ChordPro format display
• Export: Download tabs as .cho files or copy to clipboard

See CHORDPRO.md for detailed ChordPro documentation.

Managing Favorites

• View all favorites on the home page
• Export favorites to JSON file for backup
• Import favorites from JSON file

Dark Mode

• Click the 🌓 icon to toggle dark/light mode
• Respects system preference by default
• Preference saved in browser localStorage

Progressive Web App (PWA)

Freetar can be installed as a standalone app on your device:

Mobile (Android/iOS):

1. Visit the site in your mobile browser
2. Look for the "Add to Home Screen" prompt or option in the browser menu
3. Tap "Add" or "Install" to install the app
4. Launch from your home screen like a native app

Desktop (Chrome/Edge):

1. Visit the site in Chrome or Edge
2. Look for the install icon (⊕) in the address bar
3. Click it and confirm to install
4. Access from your applications menu or taskbar

PWA Benefits:

• Works offline - Access your favorites and previously viewed tabs without internet
• Faster loading - Cached resources load instantly
• Native app experience - No browser UI, full screen mode
• Auto-updates - Service worker updates automatically with new versions

Building for Production

npm run build
npm start

Or deploy to Vercel:

vercel

Privacy

Freetar respects your privacy:

• Anonymous users: all favorites stored locally in your browser (localStorage)
• Authenticated users: favorites and setlists stored in your own Airtable base
• No analytics or tracking of any kind
• Searches and tab requests are proxied through the Next.js API routes (no browser CORS)

Credits

• All chord and tab data is provided by Ultimate Guitar
• This project is not affiliated with Ultimate Guitar
• Original Python version: freetar

License

GPL 3.0 - See LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

If you encounter any issues, please open an issue on GitHub.