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

> Integrate PicList-Core into your Node.js app by installing the piclist package, creating a PicGo instance, and using the upload method for programmatic image uploads.

- Repository: [Kuingsmile/piclist-core](https://github.com/kuingsmile/piclist-core)
- Tags: how-to-guide
- Published: 2026-03-05

---

**To integrate PicList-Core into a custom Node.js application, install the `piclist` package, import the `PicGo` class from [`src/core/PicGo.ts`](https://github.com/kuingsmile/piclist-core/blob/main/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.

```bash
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`](https://github.com/kuingsmile/piclist-core/blob/main/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`](https://github.com/kuingsmile/piclist-core/blob/main/src/core/PicGo.ts) rather than the constructor directly.

```javascript
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`](https://github.com/kuingsmile/piclist-core/blob/main/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`](https://github.com/kuingsmile/piclist-core/blob/main/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.

```javascript
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`](https://github.com/kuingsmile/piclist-core/blob/main/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.

```javascript
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`](https://github.com/kuingsmile/piclist-core/blob/main/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`](https://github.com/kuingsmile/piclist-core/blob/main/src/core/PicGo.ts)), providing a pre-configured HTTP client with the same timeout and retry settings used by the core uploaders.

```javascript
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`](https://github.com/kuingsmile/piclist-core/blob/main/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`](https://github.com/kuingsmile/piclist-core/blob/main/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`](https://github.com/kuingsmile/piclist-core/blob/main/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`](https://github.com/kuingsmile/piclist-core/blob/main/src/core/PicGo.ts) detects the clipboard content and uploads it, returning the standard `IImgInfo` array containing the resulting URLs.