Local Development Setup
Relevant source files
The following files were used as context for generating this wiki page:This document provides a comprehensive guide to setting up and running the nodejs-news-feeder project on a local machine. The project is designed to aggregate news, releases, and discussions related to the Node.js ecosystem and compile them into an RSS feed and a static website. The local development environment allows contributors to test changes, run data collection scripts, and manage content before it is deployed.
Setting up a local environment involves cloning the repository, installing the necessary dependencies, and using a set of npm scripts to perform tasks such as linting, testing, and building the feed. A key feature of the local setup is a small Express.js server that facilitates the manual addition of news items, which is useful for content that cannot be collected automatically.
Sources: README.md:5-13, README.md:60-64
Prerequisites & Installation
Before starting, ensure your development environment meets the specified Node.js and npm version requirements. The installation process is straightforward, involving cloning the repository and installing dependencies using npm.
Sources: README.md:60-64, package.json:30-33
System Requirements
The project requires specific versions of Node.js and npm to ensure compatibility and stable execution.
| Tool | Version Requirement |
|---|---|
node | >=22.0.0 |
npm | >=9.6.4 |
Sources: package.json:31-32
Installation Steps
Follow these steps to get the project running locally. The nvm use command is recommended to switch to the correct Node.js version if you are using Node Version Manager.
# 1. Clone the repository
git clone https://github.com/nodejs/nodejs-news-feeder
# 2. Navigate into the project directory
cd nodejs-news-feeder
# 3. Use the correct node version (optional, for nvm users)
nvm use
# 4. Install project dependencies
npm install
Sources: README.md:61-64
The following diagram illustrates the basic setup flow.
This diagram shows the sequence of commands for setting up the local development environment.
Sources: README.md:61-64
Development Scripts
The project includes a suite of npm scripts defined in package.json to automate common development tasks. These scripts cover code linting, testing, data collection, and building the RSS feed and website.
Sources: package.json:7-22, README.md:67-89
| Script | Description |
|---|---|
npm start | Starts a local Express server for adding manual posts. |
npm run lint | Runs the standard linter to check for code style issues. |
npm run lint:fix | Automatically fixes linting issues found by standard. |
npm test | Executes the test suite using Node.js's native test runner. |
npm run test:watch | Runs tests in watch mode, re-running them when files change. |
npm run test:coverage | Runs tests and generates a code coverage report. |
npm run collect:manual | Collects posts from manual-posts.json and adds them to the feed. |
npm run rss:build | Updates feed.xml with the latest news and sets the lastBuildDate. |
npm run rss:format | Parses, sorts, filters, and formats the feed.xml file for consistency. |
npm run rss:validate | Validates the current feed.xml against the W3C Feed Validation Service. |
npm run website:build | Generates the index.html static site from the feed.xml content using an EJS template. |
Sources: package.json:7-22, README.md:67-89
Manual Post Entry
For news items that are not automatically sourced from GitHub, the project provides a local web server to manually add posts. This feature is essential for including curated content in the feed.
Sources: server.js, add-post.html, scripts/collect-manual-posts.js
Local Server for Manual Posts
Running npm start launches a simple Express.js server on http://localhost:3000. This server hosts the add-post.html page, which provides a form to submit new posts.
The server exposes two API endpoints to handle the creation and retrieval of posts, which are stored in a manual-posts.json file at the root of the project.
Sources: server.js:4-11, server.js:28-46
The sequence diagram below shows the process of a user adding a new post.
This diagram illustrates the interactions between the user's browser, the local Express server, and the JSON file when adding a manual post.
Sources: server.js, add-post.html:43-78
API Endpoints
The local server provides the following endpoints for managing manual posts.
| Method | Endpoint | Description |
|---|---|---|
GET | / | Serves the add-post.html page, which contains the form for adding new posts. |
GET | /api/posts | Retrieves all posts currently stored in manual-posts.json. Returns an empty array if the file does not exist. |
POST | /api/posts | Adds a new post to manual-posts.json. It reads the existing posts, appends the new one with a generated id and published_at timestamp, and writes the updated array back to the file. |
Sources: server.js:10-12, server.js:14-26, server.js:28-46
Consuming Manual Posts
After posts are added to manual-posts.json, the npm run collect:manual script is used to process them. This script reads the JSON file, formats each entry into a valid RSS <item> using the composeFeedItem utility, and injects the resulting XML into the main feed.xml.
Sources: scripts/collect-manual-posts.js:7-28
Summary
The local development setup for nodejs-news-feeder is designed to be simple and efficient. It relies on Node.js and a set of npm scripts to handle all aspects of development, from code quality checks to content generation and validation. The inclusion of a local server for manual post entry provides a flexible way to manage curated content alongside automatically collected news, ensuring a comprehensive and well-maintained feed. Following the steps in this guide will allow any developer to quickly get a functional environment running to contribute to the project.
Sources: README.md, package.json