Skip to content
BranchesTags
 
 

Repository files navigation

📓 WorkLin

A powerful, open-source workspace platform inspired by Notion. WorkLin combines the flexibility of block-based editing with real-time collaboration, AI assistance, and enterprise-grade features.

WorkLin License TypeScript React

✨ Features

Core Features

  • 📄 Page Management: Create, organize, and manage pages with rich metadata
  • 🧱 Block-Based Editor: Rich text editing with TipTap (headings, lists, code, tables, embeds)
  • 🔄 Real-time Collaboration: Multi-user editing with Yjs (coming soon)
  • 🔐 Authentication: Firebase Auth with email and Google sign-in
  • 💾 Cloud Sync: All data synced to Firebase Firestore
  • 📁 Workspace Management: Multiple workspaces with sharing and permissions
  • 🎨 Modern UI: Beautiful interface with ShadCN UI and Tailwind CSS
  • 🌙 Dark Mode: Full dark mode support
  • 📱 Responsive: Works seamlessly on desktop, tablet, and mobile

Advanced Features (In Progress)

  • 🤖 AI Writing Assistant: Generate, summarize, and improve content
  • 💬 Comments & Mentions: Collaborate with threaded comments
  • 📊 Database Views: Table, Board (Kanban), and Calendar views
  • 🔍 Advanced Search: Full-text search with filters
  • 📤 Export: Export pages as PDF, Markdown, or HTML
  • 🔗 Page Linking: Bidirectional links between pages
  • 📋 Templates: Create and use page templates
  • 📈 Analytics: Workspace statistics and insights

🚀 Quick Start

Prerequisites

  • Node.js 18+ and npm
  • Firebase account (for cloud features)
  • Git

Installation

# Clone the repository
git clone https://github.com/fyiclub-vitb/WorkLin.git
cd WorkLin

# Install dependencies (REQUIRED)
npm install

# If you get esbuild errors, run this first:
# Remove-Item -Recurse -Force node_modules
# Remove-Item -Force package-lock.json
# npm cache clean --force
# npm install

# Start development server
npm run dev

⚠️ Important:

  • Run npm install first! This installs all dependencies including react-router-dom
  • If you get esbuild version errors, delete node_modules and package-lock.json, then run npm install again
  • See QUICK_FIX.md or double-click FIX_AND_RUN.bat for automated fix

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

🎯 Demo Credentials

Try WorkLin instantly with demo credentials:

Email: demo@worklin.com
Password: demo123

**Test User Credentials:**
Email: test@worklin.local
Password: Password123!

Quick Start:

  1. Visit the landing page at http://localhost:3000
  2. Click "Get Started" button
  3. On login page, click "Use Demo Credentials" button (auto-fills)
  4. Or manually enter: demo@worklin.com / demo123
  5. Start using WorkLin! 🚀

Environment Setup

1. Firebase Setup (Required for Cloud Features)

  1. Create a Firebase project at https://console.firebase.google.com
  2. Enable Authentication (Email/Password and Google)
  3. Create a Firestore database
  4. Copy your Firebase config to .env file: 
    VITE_FIREBASE_API_KEY=your-api-key
VITE_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=your-project-id
VITE_FIREBASE_STORAGE_BUCKET=your-project.appspot.com
VITE_FIREBASE_MESSAGING_SENDER_ID=your-sender-id
VITE_FIREBASE_APP_ID=your-app-id
  5. Set up Firestore security rules (see firestore.rules)
  6. Set up Storage security rules (see storage.rules)

2. Cloudinary Setup (Free - 25GB Storage)

WorkLin uses Cloudinary for image storage (free tier with 25GB).

  1. Sign up at https://cloudinary.com/users/register/free (no credit card needed)
  2. Get your credentials from Dashboard:
    • Cloud Name
    • API Key
    • API Secret
  3. Create an Upload Preset:
    • Go to Settings > Upload > Upload presets
    • Add new preset: worklin_upload
    • Set Signing mode: Unsigned
  4. Add to .env file: 
    VITE_CLOUDINARY_CLOUD_NAME=your-cloud-name
VITE_CLOUDINARY_API_KEY=your-api-key
VITE_CLOUDINARY_UPLOAD_PRESET=worklin_upload

See MIGRATE_TO_CLOUDINARY.md for detailed setup instructions.

3. Render Setup (Optional - For Real-time Collaboration)

For real-time collaboration features, deploy the Yjs server on Render (free tier):

  1. Sign up at https://render.com (use GitHub to sign in)
  2. Create a new Web Service
  3. Connect your GitHub repository: https://github.com/fyiclub-vitb/WorkLin
  4. Configure the service settings:
    • Name: worklin-yjs-server (or any name you prefer)
    • Region: Choose closest to you (e.g., Oregon, Frankfurt)
    • Branch: main
    • Root Directory: yjs-server ⚠️ Important: Must be yjs-server, not src
    • Build Command: npm install
    • Start Command: npm start (or node server.js)
    • Instance Type: Free
  5. Click Create Web Service and wait for deployment (2-5 minutes)
  6. Once deployed, get your WebSocket URL:
    • Your service URL will be: https://worklin-yjs-server.onrender.com
    • WebSocket URL: wss://worklin-yjs-server.onrender.com (use wss:// for secure WebSocket)
  7. Add to your .env file: 
    VITE_YJS_WEBSOCKET_URL=wss://worklin-yjs-server.onrender.com
    (Replace with your actual Render service URL)

Important Notes:

  • ✅ Collaboration is optional. The app works perfectly without it!
  • ✅ Use wss:// (secure WebSocket) not ws:// for production
  • ✅ The server automatically uses the PORT environment variable set by Render
  • ✅ Free tier spins down after 15 minutes of inactivity (takes ~30 seconds to wake up)

For Production Deployment:

  • Add VITE_YJS_WEBSOCKET_URL to your frontend hosting platform's environment variables:
    • Vercel: Settings → Environment Variables
    • Netlify: Site settings → Environment variables

4. Google Gemini API Setup (Optional - For AI Features)

WorkLin includes AI writing assistance powered by Google Gemini.

  1. Get your API key from Google AI Studio
  2. Add to your root .env file: 
    VITE_GEMINI_API_KEY=your-gemini-api-key
  3. Restart your dev server if running: 
    npm run dev

Rate Limits: 15 requests per minute per user (client-side rate limiting)

Free Tier: 60 RPM, 1,500 requests/day - No credit card required!

Note: The API key is used directly in the frontend. For production, set VITE_GEMINI_API_KEY in your hosting platform's environment variables (Vercel, Netlify, etc.).

See GEMINI_API_SETUP.md for detailed setup instructions.

📦 Available Scripts

# Development server
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

# Type checking
npm run lint

🛠️ Tech Stack

Frontend

  • Framework: React 18.2+ with Vite
  • Language: TypeScript 5.0+ (strict mode)
  • Styling: Tailwind CSS 3.3+ with ShadCN UI
  • Icons: Lucide React
  • State Management: Zustand
  • Rich Text Editor: TipTap
  • Animations: Framer Motion
  • UI Components: Radix UI + ShadCN

Backend & Database

  • Database: Firebase Firestore
  • Authentication: Firebase Auth
  • Storage: Cloudinary (25GB free tier) - Image and file storage
  • Functions: Firebase Cloud Functions
  • Hosting: Firebase Hosting, Vercel, or Render
  • Collaboration Server: Render (free tier) - Yjs WebSocket server

Collaboration

  • Real-time Sync: Yjs + WebRTC (or Firebase)
  • Presence: Firebase Realtime Database

DevOps

  • Build Tool: Vite 4.4+
  • Testing: Vitest + Playwright
  • Linting: ESLint + Prettier

📁 Project Structure

worklin/
├── src/
│   ├── components/          # React components
│   │   ├── ui/              # ShadCN UI components
│   │   ├── editor/          # TipTap editor components
│   │   ├── auth/            # Authentication components
│   │   ├── collaboration/   # Real-time collaboration
│   │   ├── workspace/       # Workspace management
│   │   └── ...              # Other components
│   ├── lib/                 # Library code
│   │   ├── firebase/        # Firebase services
│   │   │   ├── config.ts
│   │   │   ├── auth.ts
│   │   │   ├── database.ts
│   │   │   └── storage.ts
│   │   └── utils.ts         # Utility functions
│   ├── store/               # Zustand stores
│   │   └── workspaceStore.ts
│   ├── hooks/               # Custom React hooks
│   ├── types/               # TypeScript types
│   └── styles/              # Global styles
├── public/                  # Static assets
├── env.example              # Environment variables template
├── GITHUB_ISSUES.md         # 30 open source issues
├── package.json
├── vite.config.ts
└── tsconfig.json

🎯 Usage

Creating Pages

  1. Click the "New Page" button in the sidebar
  2. The new page will appear in the sidebar
  3. Click on it to start editing

Managing Pages

  • Delete Page: Click the trash icon next to a page to move it to trash
  • Trash View: Click "Trash" in the sidebar to view deleted pages
  • Restore Page: In trash view, click the restore icon to restore a page
  • Permanent Delete: In trash view, click the permanent delete icon to permanently remove a page
  • Home: Click "Home" in the sidebar to clear page selection and return to home view

Adding Blocks

  1. Click "Add Block" at the bottom of the editor
  2. Or press Enter while editing a block to create a new one below

Block Types

  • Text: Regular paragraph text (auto-expanding textarea)
  • H1, H2, H3: Headings with different sizes
  • List: Bulleted list items
  • Todo: Checkbox items with strikethrough when checked

Editing Blocks

  • Click on any block to edit
  • Change block type using the dropdown on hover
  • Delete blocks using the trash icon on hover
  • Press Enter to create a new block below

🤝 Contributing

We welcome contributions! This project is part of ACWOC (All Contributors Welcome Open Challenge). Please see CONTRIBUTING.md for guidelines.

Getting Started

  1. Fork the repository
  2. Check out GITHUB_ISSUES.md for 30 open issues ranging from easy to hard
  3. Comment on an issue to claim it
  4. Create your feature branch (git checkout -b feature/issue-{number}-{description})
  5. Make your changes
  6. Commit your changes (git commit -m 'Add: description of changes')
  7. Push to the branch (git push origin feature/issue-{number}-{description})
  8. Open a Pull Request

Issue Difficulty Levels

  • 🟢 Easy: Good for beginners, simple UI components, basic features
  • 🟡 Medium: Intermediate features, integrations, complex UI
  • 🔴 Hard: Advanced features, real-time systems, complex algorithms

See GITHUB_ISSUES.md for the complete list of 30 issues!

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🎯 Roadmap

  • Basic block-based editor
  • Firebase integration
  • Cloudinary image storage (25GB free)
  • Authentication (demo mode)
  • Workspace management
  • Trash system with restore functionality
  • Settings page
  • Landing page
  • Login page with demo credentials
  • Responsive design (mobile-friendly)
  • Dark mode support
  • Real-time collaboration (Yjs + Render) - See Issue #21
  • AI writing assistant - See Issue #23
  • Database views - See Issue #14
  • Comments system - See Issue #12
  • Page templates - See Issue #13
  • Advanced search - See Issue #8, #19
  • Export functionality - See Issue #16
  • Mobile app/PWA - See Issue #25

Check GITHUB_ISSUES.md for 30 open issues ready for contributors!

🙏 Acknowledgments

  • Inspired by Notion's block-based editor
  • Built with React, Vite, Tailwind CSS, Firebase, and TipTap
  • UI components from ShadCN UI
  • Icons provided by Lucide

🔗 Links

Discussions

💬 Have questions or doubts? Please use the Discussions tab to ask and interact with maintainers.

Made with ❤️ by the WorkLin team

About

Worklin is a lightweight,open-source notes workspace inspired by Notion. Create pages, organize in sidebar, and edit using simple blocks (headings, paragraphs, bullets, checklists). Built with React, Vite, Tailwind CSS. Features client-side persistence, keyboard editing, and extensible architecture. Perfect for students and developers. MIT-licensed

worklin-fyi.vercel.app/

Resources

Readme
License

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages