Discourse CSV Importer

A simple, lightweight tool to bulk import topics and categories into Discourse forums from CSV files.

🚀 Features

• ✅ Bulk import topics from CSV files
• ✅ Auto-create categories and subcategories
• ✅ Support for tags and topic pinning
• ✅ Rate limiting to avoid API throttling
• ✅ Environment variable configuration
• ✅ Error handling with detailed feedback
• ✅ Duplicate detection and graceful handling

📋 Prerequisites

• Node.js 14+
• A Discourse forum with admin access
• Discourse API key with appropriate permissions

🛠️ Installation

1. Clone the repository:

   git clone https://github.com/qabalany/discourse-csv-importer.git
   cd discourse-csv-importer

2. Install dependencies:

   npm install

3. Configure environment:

   cp .env.example .env
   # Edit .env with your actual values 

⚙️ Configuration

Create a .env file with your Discourse settings:

DISCOURSE_URL=https://your-forum.discourse.com
DISCOURSE_API_KEY=your-api-key-here
DISCOURSE_USERNAME=your-admin-username
CSV_FILE=example.csv
REQUEST_DELAY=1000

Getting Your API Key

1. Go to your Discourse admin panel
2. Navigate to API → Keys
3. Create a new API key with appropriate permissions
4. Copy the key to your .env file

📝 CSV Format

Your CSV file should have these columns:

Column	Required	Description
category	✅	Category name (supports subcategories with /)
topic_title	✅	Title of the topic
post_content	✅	Content of the first post
tags	❌	Comma-separated tags
pinned	❌	"yes" to pin the topic
author	❌	Username (defaults to API user)

Example CSV:

category,topic_title,post_content,pinned,author,tags
"General",Welcome Post,"Welcome to our forum!",yes,admin,"welcome,intro"
"Tech/AI",AI Discussion,"Let's discuss AI trends",no,moderator,"ai,tech"
"Support",FAQ,"Frequently asked questions",yes,admin,"faq,help"

🚀 Usage

1. Prepare your CSV file with the required format
2. Set your environment variables in .env
3. Run the importer:

   npm start

📊 Example Output

📂 Loaded 4 topics from example.csv
✅ Loaded 3 existing categories
🟢 Created category: Tech Discussion
📝 Creating topic: Welcome to Our Forum
✅ Created topic: Welcome to Our Forum
📌 Pinned topic: Welcome to Our Forum
📝 Creating topic: Getting Started Guide
✅ Created topic: Getting Started Guide
📌 Pinned topic: Getting Started Guide
🎉 All topics processed!

🛡️ Error Handling

The tool handles common scenarios:

• Duplicate topics: Skips existing topics gracefully
• Missing categories: Creates them automatically
• Rate limiting: Includes delays between requests
• API errors: Detailed error messages for troubleshooting

🤝 Contributing

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

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

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

🆘 Support

If you encounter any issues:

1. Check the Issues page
2. Create a new issue with:
   • Your Node.js version
   • Error messages (remove sensitive data)
   • CSV format example

🙏 Acknowledgments

• Thanks to the Discourse team for their excellent API
• Built with axios and csv-parser