Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Scriptwriter

A real-time collaborative screenwriting app. Write screenplays with proper formatting, together with others or solo — changes sync instantly between everyone in the same script, and everything is stored in PostgreSQL.

Built with React, TypeScript, Express, and Yjs CRDTs for conflict-free collaborative editing over WebSockets.

Features

  • Screenplay-native editing — dedicated block types for scene headings, action, dialogue, parentheticals, transitions, and notes, with characters attached to dialogue
  • Real-time collaboration — multiple writers in the same script see each other's edits and presence live; conflict-free merging via Yjs, so nobody overwrites anyone
  • Keyboard-first workflow — insert any block type, add scenes, and navigate the whole script without touching the mouse (see shortcuts)
  • Scenes & structure — scene sections with draft/review/final status, locking, and act breaks
  • Characters — per-script character list with colors and descriptions, and a quick character selector when writing dialogue
  • Ideas board — a separate brainstorming tab per script for loose notes and ideas
  • Version history — automatic revisions every 5 minutes (and on every connect), with one-click restore to any earlier version
  • Soft delete — deleted scripts can be restored for 7 days before being purged
  • Export & import — print/PDF export in screenplay format, plus JSON export/import (including ideas) for backup or moving between instances
  • Optional password protection — a single shared password gates the app (JWT-based, with login rate limiting); leave it unconfigured for open/local use
  • Light & dark theme

Running locally

You can run Scriptwriter entirely on your own machine — collaboration is optional, it works fine as a single-user writing tool.

Prerequisites

  • Node.js 20+
  • PostgreSQL running locally

Setup

git clone <this-repo>
cd scriptwriter
npm install

# Create the database (migrations run automatically on server start)
createdb scriptwriter

# Configure environment
cp .env.example .env

The default .env works out of the box if PostgreSQL runs on localhost:5432:

DATABASE_URL=postgresql://localhost:5432/scriptwriter
PORT=3001

Development

npm run dev

This starts the Vite dev server (frontend, http://localhost:5173) and the Express/WebSocket server (backend, port 3001) together. Open http://localhost:5173.

Running as a local "production" app

If you just want to use the app rather than develop it:

npm run build
NODE_ENV=production npm start

The server then serves the built frontend itself — open http://localhost:3001.

Password protection (optional)

By default there is no login — anyone who can reach the server can use it, which is fine locally. To require a shared password (recommended for anything reachable from the internet):

npm run set-password

This prompts for a password and writes PASSWORD_HASH (bcrypt) and a random JWT_SECRET to .env. Restart the server and visitors must enter the password once; they then get a token valid for 7 days. Login attempts are rate-limited (5 per 15 minutes per IP).

Deploying

The app is a single Node process serving both the API/WebSockets and the built frontend, so it deploys to any Node host (Railway, Render, Fly.io, a VPS…) with a PostgreSQL database attached.

Build command: npm run build — start command: npm start

Environment variables

Variable Required Description
DATABASE_URL yes PostgreSQL connection string
NODE_ENV yes (in prod) Set to production so the server serves the built frontend from dist/
PORT no Port to listen on (defaults to 3001; most hosts set this for you)
PASSWORD_HASH no bcrypt hash of the shared password — generate with npm run set-password and copy it from the local .env
JWT_SECRET if password is set Secret for signing login tokens — use a long random string

Database migrations run automatically when the server starts.

Keyboard shortcuts

Shortcut Action
Ctrl+Shift+A Insert action block
Ctrl+Shift+S Insert dialogue block
Ctrl+Shift+D Insert parenthetical
Ctrl+Shift+Z Insert transition
Ctrl+Shift+X Insert note
Ctrl+Shift+E New scene
Ctrl+Shift+Q Delete focused block
Tab / Shift+Tab Next / previous block
↑ / ↓ Move between blocks at text boundaries
Ctrl/Cmd+Z Undo
Ctrl/Cmd+F Search
Esc Close dialogs / clear search

Tech stack

  • Frontend: React 19, TypeScript, Vite, Tailwind CSS, dnd-kit (drag & drop)
  • Backend: Express 5, ws WebSockets, Yjs + y-protocols for CRDT sync
  • Database: PostgreSQL (scripts stored as both Yjs binary state and queryable JSON/relational tables)
  • Auth: bcrypt password hash + JWT

License

MIT

Project structure

server/          Express + WebSocket server, auth, DB access, SQL migrations
src/             React frontend
  components/    Editor canvas, toolbar, dashboard, export, ideas board, …
  hooks/         useYjsScript — Yjs document binding + WebSocket sync
  yjs-schema.ts  Script ⇄ Y.Doc conversion
  state.ts       Script state reducer and initial state

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages