SyncFolderPushCommand

The SyncFolderPushCommand is a high-level command designed to efficiently synchronize a local directory with a remote directory in your DID Space. It intelligently compares the local and remote states, uploading new or modified files and, optionally, deleting remote files that no longer exist locally. This command simplifies common tasks like deploying static websites, backing up important data, or distributing digital assets.

It handles complexities like concurrency, retries, and consistency checks, providing a robust and straightforward way to manage folder synchronization.

Use Cases#

• Deploying Static Websites: Push your local build directory (e.g., ./dist, ./build) to a public folder in your DID Space to deploy or update a website.
• Data Backup: Regularly sync a local folder containing important documents or user data to your DID Space for a secure backup.
• Asset Distribution: Upload a folder of images, videos, or other assets that your application needs to serve to users.

Input Parameters#

The SyncFolderPushCommand accepts the following parameters in its input object.

Output#

The command returns a Promise that resolves to the following object.

Example#

This example demonstrates how to sync a local folder named ./my-blog-dist to the /blog/ directory in a DID Space.

import { SpaceClient, SyncFolderPushCommand } from '@blocklet/did-space-js';
import getWallet from '@blocklet/sdk/lib/wallet';
import path from 'path';
import fs from 'fs-extra';

// Ensure the source directory and some files exist for the example
const sourceDir = path.join(__dirname, 'my-blog-dist');
fs.ensureDirSync(sourceDir);
fs.writeFileSync(path.join(sourceDir, 'index.html'), '<h1>Hello World</h1>');
fs.ensureDirSync(path.join(sourceDir, 'assets'));
fs.writeFileSync(path.join(sourceDir, 'assets', 'style.css'), 'body { color: #333; }');

async function syncWebsite() {
  const wallet = getWallet();
  const client = new SpaceClient({
    endpoint: 'https://www.didspaces.com/app/api/space/...',
    wallet,
  });

  const command = new SyncFolderPushCommand({
    source: sourceDir,
    target: '/blog/',
    strictSync: true, // Delete remote files not in the source
    onProgress: ({ completed, total }) => {
      const percentage = total > 0 ? ((completed / total) * 100).toFixed(2) : 0;

Example Response (Success)#

{
  "statusCode": 200,
  "data": {
    "size": 48,
    "errorCount": 0,
    "count": 2,
    "duration": 1.25
  }
}

Best Practices#

Ensuring Data Consistency#

When syncing files, especially from a directory that might be actively written to, there's a risk of uploading an incomplete or corrupted file. To prevent this, the SyncFolderPushCommand first copies each file to a temporary directory before uploading. This ensures that a stable snapshot of the file is used for the upload, safeguarding against Unexpected end of form errors and ensuring data integrity.

Using strictSync Safely#

The strictSync: true option is powerful for ensuring the remote directory is an exact mirror of the local source. However, it is a destructive operation. Any file on the remote server that is not present in the local source directory will be permanently deleted. Always double-check your source and target paths before enabling this option.

Custom Filtering#

You can use the filter function to gain fine-grained control over which files are synchronized. For example, you can exclude dotfiles, log files, or specific directories.

const command = new SyncFolderPushCommand({
  source: './project',
  target: '/my-project/',
  filter: (object) => {
    // Exclude all files starting with a dot (e.g., .DS_Store, .env)
    if (object.name.startsWith('.')) {
      return false;
    }
    // Exclude the node_modules directory
    if (object.key.includes('/node_modules/')) {
      return false;
    }
    return true;
  },
});