devflux

DevFlux

A TypeScript SDK for the dev.to API with full type safety and comprehensive documentation.

Features

✨ Full TypeScript Support - Built with TypeScript, includes comprehensive type definitions
📚 Extensive Documentation - JSDoc comments on all methods and types
🎯 Type-Safe - Catch errors at compile time, not runtime
🚀 Modern - Supports both ESM and CommonJS
🪶 Lightweight - Zero dependencies
🔧 Flexible - Customizable configuration options

Installation

npm install devflux

Or with yarn:

yarn add devflux

Or with pnpm:

pnpm add devflux

Quick Start

import { DevFluxClient } from 'devflux';

// Create a client instance
const client = new DevFluxClient();

// Fetch articles
const articles = await client.getArticles({ per_page: 10 });

console.log(articles[0].title);

Usage Examples

Fetch Articles by Username

const client = new DevFluxClient();

// Get all articles by a specific user
const articles = await client.getArticlesByUsername('zororaka', {
  page: 1,
  per_page: 30
});

articles.forEach(article => {
  console.log(`${article.title} - ${article.readable_publish_date}`);
});

Fetch Articles by Tag

const client = new DevFluxClient();

// Get articles tagged with 'javascript'
const jsArticles = await client.getArticlesByTag('javascript', {
  per_page: 20
});

Fetch Top Articles

const client = new DevFluxClient();

// Get top articles from the last 7 days
const topWeekly = await client.getTopArticles(7);

// Get top articles from the last month
const topMonthly = await client.getTopArticles(30);

// Get top articles of all time
const topAllTime = await client.getTopArticles(Infinity);

Fetch a Specific Article

const client = new DevFluxClient();

// By article ID
const article = await client.getArticleById(123456);

// By username and slug
const article = await client.getArticleByPath('zororaka', 'my-awesome-post');

console.log(article.title);
console.log(article.description);
console.log(article.url);

Pagination Support

const client = new DevFluxClient();

// Get paginated results with metadata
const response = await client.getArticlesPaginated({
  page: 1,
  per_page: 30
});

console.log(response.data); // Array of articles
console.log(response.hasMore); // Whether there are more pages
console.log(response.page); // Current page number
console.log(response.perPage); // Items per page

Fetch Fresh or Rising Articles

const client = new DevFluxClient();

// Get recently published articles
const freshArticles = await client.getFreshArticles();

// Get trending articles
const risingArticles = await client.getRisingArticles();

API Reference

DevFluxClient

The main client class for interacting with the dev.to API.

Constructor

new DevFluxClient()

Creates a new DevFlux client instance. No configuration needed - works out of the box!

Methods

getArticles(params?: ArticleQueryParams): Promise<Article[]>

Fetches a list of articles.

Parameters:

• page (number): Page number for pagination
• per_page (number): Number of articles per page (max: 1000)
• tag (string): Filter by tag
• tags (string): Filter by tags (comma-separated)
• tags_exclude (string): Exclude tags (comma-separated)
• username (string): Filter by username
• state ('fresh' | 'rising' | 'all'): Filter by state
• top (number): Filter by top articles (days)
• collection_id (number): Filter by collection ID

getArticlesByUsername(username: string, params?: ArticleQueryParams): Promise<Article[]>

Fetches articles by a specific username.

getArticleById(id: number): Promise<Article>

Fetches a single article by its ID.

getArticleByPath(username: string, slug: string): Promise<Article>

Fetches a single article by username and slug.

getArticlesPaginated(params?: ArticleQueryParams): Promise<PaginatedResponse<Article>>

Fetches articles with pagination metadata.

getArticlesByTag(tag: string, params?: ArticleQueryParams): Promise<Article[]>

Fetches articles by tag.

getTopArticles(days: number, params?: ArticleQueryParams): Promise<Article[]>

Fetches top articles from a specified time period.

getFreshArticles(params?: ArticleQueryParams): Promise<Article[]>

Fetches recently published articles.

getRisingArticles(params?: ArticleQueryParams): Promise<Article[]>

Fetches trending articles.

TypeScript Types

DevFlux exports comprehensive TypeScript types:

import type {
  Article,
  User,
  Organization,
  FlareTag,
  ArticleQueryParams,
  PaginatedResponse
} from 'devflux';

Article

Complete article object with all fields from the dev.to API.

User

User/author information.

Organization

Organization details.

ArticleQueryParams

Query parameters for filtering and pagination.

PaginatedResponse<T>

Wrapper for paginated results with metadata.

Error Handling

DevFlux throws errors when API requests fail:

try {
  const articles = await client.getArticles();
} catch (error) {
  console.error('Failed to fetch articles:', error.message);
}

Contributing

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

• Fork the repository
• Create your feature branch (git checkout -b feature/amazing-feature)
• Commit your changes (git commit -m 'Add some amazing feature')
• Push to the branch (git push origin feature/amazing-feature)
• Open a Pull Request

License

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

Links

• npm Package
• GitHub Repository
• dev.to API Documentation

Acknowledgments

Built with ❤️ for the dev.to community.