用 React、Express 和 PostgreSQL 建立手機吉他調音器

If you want a guitar tuner that is easy to open on a phone or smartwatch, a small local web app can be more practical than a native installation. The hard part is not drawing six buttons. It is keeping the local setup reproducible while making the browser experience usable on a small screen.

This tutorial walks through the current main branch of Guitar Tune Trainer, an MIT-licensed open-source project owned by Fernando Paladini. You will install the project, start its PostgreSQL service, run the checks and production build, and understand what the repository currently does and does not provide.

TL;DR

The project is a React and Vite front end served by an Express application. Its documented local path is:

1. Install Node.js 18+, npm, and PostgreSQL support.
2. Clone the repository and run npm install.
3. Start PostgreSQL with the included Docker Compose file, or use another local database.
4. Copy .env.sample to .env and set a local SESSION_SECRET.
5. Run npm run db:push, then npm run dev.

The current repository also passes npm ci, npm run check, and npm run build on commit 26cfe55744aad30f2d30f03cdf70244bc0a91809.

Prerequisites

You need:

• Node.js 18 or newer
• npm
• Docker Desktop with Compose, or a reachable PostgreSQL database
• A modern browser if you want to use the mobile-oriented interface

The repository has no GitHub release or stable tag at the time of writing. Treat the commands below as instructions for the current main branch, not as a promise that a future release will have identical dependencies.

Start PostgreSQL locally

The repository includes a small docker-compose.yml that starts PostgreSQL 16 with a named volume:

docker compose up -d

The checked-in Compose configuration uses these local development values:

POSTGRES_USER: postgres
POSTGRES_PASSWORD: postgres
POSTGRES_DB: guitar_tune_trainer

It publishes PostgreSQL on port 5432. These are development credentials from the repository configuration. Do not reuse them on a shared or internet-exposed database.

If port 5432 is already occupied, either stop the conflicting service or change the host-side port mapping. If you change the host port, update the connection string accordingly.

Install and configure the app

Clone the project and install the lockfile dependencies:

git clone https://github.com/paladini/guitar-tune-trainer.git
cd guitar-tune-trainer
npm ci

The current package.json identifies the package as version 1.0.0, uses ES modules, and declares the MIT license. Its scripts include dev, build, start, check, and db:push.

Create the local environment file from the checked-in example:

cp .env.sample .env

On Windows PowerShell, use this equivalent command:

Copy-Item .env.sample .env

The example contains:

DATABASE_URL=postgres://postgres:postgres@localhost:5432/guitar_tune_trainer
SESSION_SECRET=your-session-secret
PORT=5000

Replace your-session-secret with a random value before using the app beyond a disposable local session. Keep .env out of version control. The repository's .gitignore is intended to support that local configuration pattern.

Apply the database schema and run the app

The repository's Drizzle configuration reads DATABASE_URL, and the documented schema currently defines a users table with a serial ID, unique username, and password field. Apply that schema with:

npm run db:push
npm run dev

The Express entry point defaults to port 5000, listens on 0.0.0.0, and serves the Vite development app after registering the server routes. Open http://localhost:5000 in a browser.

The HTML entry point is explicitly mobile-oriented. It sets a responsive viewport, describes the page as a smartwatch and mobile guitar tuner, links a web manifest, and includes Apple web-app metadata. The README describes the project as a PWA with offline support. Verify those capabilities in the browser you intend to use rather than assuming every browser exposes the same install prompt or audio behavior.

What the current code actually provides

The project is easiest to understand as two layers:

• The client is a React application bundled with Vite and styled with Tailwind CSS and component primitives.
• The server is an Express host with Drizzle-related database configuration and a memory-backed user storage implementation.

That distinction matters. The current server/routes.ts creates the HTTP server but does not register application API endpoints. The storage class keeps users in a process-local Map, while the shared schema describes PostgreSQL tables. The repository therefore demonstrates a runnable full-stack shell and a mobile tuner experience, but it is not yet a complete account-backed production service.

This is also why the first verification target should be the local page and build, not a claim that user data is persisted across restarts.

Reproducible verification

From a clean checkout, run the same checks used for this tutorial:

npm ci
npm run check
npm run build

npm ci installs the exact versions recorded in package-lock.json. npm run check runs TypeScript checking through tsc. npm run build runs the Vite client build and bundles the Express server with esbuild into dist.

On the current commit, all three commands completed successfully. The install also reported 35 audit findings in the dependency tree: 3 low, 11 moderate, 20 high, and 1 critical. That result is a reason to review and update dependencies before exposing the app publicly, not a reason to claim that the application is secure.

After the build, you can use the production-shaped command locally:

npm start

The application still requires the configured environment and database assumptions. Stop it with Ctrl+C when the smoke test is complete.

Failure modes and boundaries

PostgreSQL does not start

Check whether port 5432 is already in use and inspect the Compose logs:

docker compose ps
docker compose logs db

If you use a managed PostgreSQL provider instead, set DATABASE_URL to that provider's connection string and follow its TLS requirements.

The browser cannot access audio features

The repository presents reference-tone functionality as part of the tuner experience, but browser audio policies vary. Test on the target phone or watch, allow audio when prompted, and do not assume that a desktop result reproduces on a wearable browser.

Database changes appear not to persist

The schema and database configuration do not mean every feature is backed by PostgreSQL. The current route file has no registered application endpoints, and MemStorage stores users only in memory. Treat persistence as an unfinished boundary until the implementation changes and is verified.

Development credentials leak into deployment

The Compose file intentionally uses simple local credentials. Replace them, restrict network exposure, use a secret manager, and rotate any credential that may have been copied outside a disposable development environment.

FAQ

Can I run it without Docker?

Yes. The README lists local, Docker, or Neon PostgreSQL as options. Set DATABASE_URL to the database you control and run the same schema command.

Is there a stable release to pin?

No GitHub release or tag was present during this review. Pin a commit when reproducibility matters, and recheck the README and package metadata before upgrading.

Is this a production-ready authentication system?

No. The current repository contains a schema and in-memory storage skeleton, not a completed authentication flow. Do not put real credentials into it without implementing and reviewing authentication, password hashing, session handling, authorization, and database persistence.

Takeaway

Guitar Tune Trainer is a useful example of a small mobile-first full-stack web project: the command surface is compact, the browser entry point is designed for small screens, and the build is easy to verify locally. Its honest value today is the runnable interface and development scaffold. Its server-side persistence and security model still need deliberate engineering before deployment.

What would you build next: browser microphone pitch detection, a completed persisted account flow, or a smaller offline-only tuner with no server at all?

AI assistance disclosure

AI assistance was used to organize this tutorial and review the documented commands against the public repository. The repository behavior, configuration values, limitations, and validation results were checked against the cited primary sources and a clean local checkout.