How to Integrate PicList-Core into a Custom Node.js Application

To integrate PicList-Core into a custom Node.js application, install the piclist package, import the PicGo class from src/core/PicGo.ts, initialize it asynchronously using PicGo.create(), and invoke the upload() method to handle image uploads programmatically.

PicList-Core, maintained in the kuingsmile/piclist-core repository, provides a modular image-upload engine that can be embedded directly into Node.js applications. Unlike the CLI version, the core library exposes a programmable PicGo class that manages configuration, plugin loading, and the upload lifecycle. This guide demonstrates how to import the package, initialize the instance, and execute uploads using the exact APIs implemented in the source code.

Installing PicList-Core in Your Project

Add the package to your Node.js project using your preferred package manager. The library is distributed as piclist on npm.

npm install piclist -D

# or

yarn add piclist -D

The -D flag installs it as a dev dependency, though you may omit this for production deployments. Once installed, the core entry point resides in src/core/PicGo.ts, where the main PicGo class orchestrates the upload lifecycle.

Initializing the PicGo Instance

The PicGo class requires asynchronous initialization to load built-in plugins, internationalization (i18n) resources, and configuration files. Use the static create method defined at lines 92-96 in src/core/PicGo.ts rather than the constructor directly.

import { PicGo } from 'piclist';

async function initializeUploader() {
  // Uses default config path ~/.piclist/config.json
  const picgo = await PicGo.create();
  
  // Or pass a custom configuration directory
  const picgoCustom = await PicGo.create('/custom/path/to/config');
  
  return picgo;
}

The initialization process invoked by create triggers src/lib/PluginLoader.ts to dynamically load third-party plugins at runtime, ensuring all uploaders and transformers are available before you queue any uploads.

Configuring Upload Behavior

Once initialized, the instance exposes methods to read and modify configuration without manually editing JSON files. According to src/utils/configManager.ts, the configuration manager handles reading and writing to the underlying storage.

• getConfig() – Retrieve current configuration values
• setConfig(key, value) – Update specific configuration keys
• saveConfig() – Persist changes to disk

You can also switch uploaders programmatically using changeCurrentUploader(), passing the uploader name (e.g., 's3', 'webdav') and its specific options object.

const picgo = await PicGo.create();

// Switch to AWS S3 uploader with credentials
picgo.changeCurrentUploader('s3', {
  accessKeyId: 'YOUR_ACCESS_KEY',
  secretAccessKey: 'YOUR_SECRET_KEY',
  bucket: 'my-image-bucket'
});

// Save the configuration for future sessions
picgo.saveConfig();

Uploading Images Programmatically

The upload() method, defined at lines 16-24 in src/core/PicGo.ts, accepts an optional array of absolute file paths. When called without arguments, it automatically uploads the image currently stored in the system clipboard. The method returns a Promise that resolves to an array of IImgInfo objects containing metadata about the uploaded images.

async function uploadLocalFile(filePath) {
  const picgo = await PicGo.create();
  
  // Upload specific files
  const results = await picgo.upload([filePath]);
  console.log('Uploaded URLs:', results.map(img => img.imgUrl));
}

async function uploadFromClipboard() {
  const picgo = await PicGo.create();
  
  // No arguments triggers clipboard upload
  const results = await picgo.upload();
  console.log('Clipboard upload result:', results);
}

The upload execution flows through src/lib/Lifecycle.ts, which coordinates the transformation pipeline (watermarking, compression via src/plugins/transformer/*) and the actual upload to remote storage via src/plugins/uploader/* (including WebDAV, SFTP, AWS S3, and Imgur implementations).

Using the HTTP Request Helper

For applications requiring direct HTTP access outside the standard upload flow, the PicGo instance exposes a request property. This proxies to the internal Request class (lines 12-14 in src/core/PicGo.ts), providing a pre-configured HTTP client with the same timeout and retry settings used by the core uploaders.

const picgo = await PicGo.create();

// Make authenticated requests using the internal HTTP client
const response = await picgo.request.get('https://api.example.com/images');

Summary

• Install via npm: Add piclist to your project dependencies.
• Import from core: The PicGo class in src/core/PicGo.ts is the primary entry point.
• Initialize asynchronously: Use PicGo.create() to load plugins and config before uploading.
• Configure programmatically: Use getConfig, setConfig, and saveConfig to manage settings, or changeCurrentUploader to switch providers.
• Upload flexibly: Pass file paths to upload() for local files, or call it without arguments to capture the clipboard.
• Access HTTP utilities: Use picgo.request for direct HTTP operations using the internal client.

Frequently Asked Questions

How do I install PicList-Core for programmatic use?

Install the piclist package from npm using npm install piclist or yarn add piclist. The core library is then imported via import { PicGo } from 'piclist', giving you access to the class defined in src/core/PicGo.ts.

Can I use a custom configuration file path instead of the default?

Yes. While PicGo.create() uses ~/.piclist/config.json by default, you can pass a custom directory path as the first argument to create(). The configuration manager in src/utils/configManager.ts will read from and write to that location instead.

What is the difference between PicGo.create() and the constructor?

PicGo.create() is a static asynchronous factory method that handles initialization tasks like loading built-in plugins and i18n resources. The constructor is synchronous and does not perform these setup steps. Always use create() when integrating into applications to ensure the instance is fully ready.

How do I upload images from the clipboard using PicList-Core?

Call the upload() method without any arguments. When invoked with an empty parameter list, the method defined at lines 16-24 in src/core/PicGo.ts detects the clipboard content and uploads it, returning the standard IImgInfo array containing the resulting URLs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}