typingmind-cloud-backup

💗 Countless hours have gone into coding this extension. If you found this useful, please consider donating so that I stay motivated to build and release such awesome tools for free. 💗

Buy Me A Coffee


**Quick Navigation** [Key Features](#-key-features) • [Installation & Setup](#-installation--setup) • [Migration to V3](#-migration-to-v3) • [Operating Modes](#-operating-modes) • [Using the Extension](#-using-the-extension) • [Cloud Storage Setup](#️-cloud-storage-setup) • [Troubleshooting](#-troubleshooting)

TypingMind Cloud Sync V3

A comprehensive cloud backup and sync extension for TypingMind that automatically backs up and synchronizes your entire TypingMind data with AWS S3 or S3-compatible cloud storage services.

✨ Key Features

🔄 Intelligent Sync System

💾 Efficient Backup Management

🔒 Security & Encryption

🛠 Flexible Configuration

📊 Monitoring & Debugging

🚀 Installation & Setup

Prerequisites

⚠️ Important: Before installing, it’s always a good practice to export your TypingMind data via “Settings > App Data & Storage > Export” as a local backup.

Step 1: Install the Extension

  1. Go to Menu > Preferences > Extensions in TypingMind.
  2. Load this URL: https://itcon-pty-au.github.io/typingmind-cloud-backup/s3-v3.js

Step 2: Configure Cloud Storage

After installation, you’ll see a new Sync button in the sidebar. Click it to open the configuration modal.

First Time Setup: If you haven’t configured the mandatory fields (bucket name, region, access key, secret key, encryption key), the extension will show an alert prompting you to configure these settings. The extension needs these credentials to function.

Required Fields (marked with *):

Optional Fields:

Step 3: Quick Setup Options

Option A: Manual Configuration

  1. Click the Sync button in the navigation menu.
  2. Fill in your cloud storage credentials in the modal.
  3. Click Save. The extension will verify credentials, and if successful, perform an initial sync.
    • If cloud is empty, it will upload your local data.
    • If local data is empty but cloud has data, it will restore from the cloud.
    • It will then start automatic sync and daily backups.

Add parameters to your TypingMind URL for automatic setup. This is useful for quickly configuring a new browser or device.

https://your-typingmind-url.com/?bucket=your-bucket&region=us-east-1&accesskey=your-key&secretkey=your-secret&encryptionkey=your-password&config

Available URL Parameters:

🎛 Operating Modes

Standard Sync Mode (Default)

NoSync Mode

Add ?nosync to your URL to enable this mode.

📱 Using the Extension

The sync modal is your central hub for managing backups and settings.

Backup Management

The Available Backups section shows all your cloud backups.

Backup Types:

Actions:

Sync Diagnostics

This panel provides a quick overview of your sync status. It helps identify discrepancies between your local data and cloud data.

Ideally, all counts should match after a successful sync.

Manual Operations

Sync Status Indicator

The sync button in the sidebar shows a colored dot indicating the current status. The dot is only visible when the extension is configured and has performed a sync operation.

🚀 Migration to V3

V3 is a major rewrite and is not backward compatible with backups created by older versions (V1 or V2).

What to Expect During Migration

When you load the V3 extension for the first time, the process is largely automatic:

⚠️ Important Compatibility Notes

There is no manual data migration required—the extension handles everything automatically on the first load. Just install, configure, and let it work.

  1. Backup Data: In TypingMind, go to Settings > App Data & Storage > Export. Select all checkboxes and download the file. Keep it in a safe place.
  2. Remove Old Version: Go to Settings > Extensions and remove the V1/V2 extension.
  3. Install V3: Load the V3 extension URL: https://itcon-pty-au.github.io/typingmind-cloud-backup/s3-v3.js.
  4. Configure: Open the Sync modal. Your previous settings should be pre-filled. Enter your Encryption Key again and click Save.
  5. Verify: The first sync will begin. You can monitor its progress in the browser console (enable logging for more detail) and by using the Sync Diagnostics panel.

Understanding the V3 File Structure

To help you safely clean up old files from previous versions, here is a breakdown of the file structure used by V3 in your S3 bucket. Any files or folders not matching this structure are likely from an older version and can be removed.

Any other files or folders at the root of your bucket, are no longer used by V3 and can be safely deleted once you have successfully migrated. This is how your S3 bucket should look like.

S3 File Structure

☁️ Cloud Storage Setup

AWS S3

  1. Create a user in Amazon IAM. On the permissions screen, you can skip adding the user to a group for now. After creating the user, open their profile.
  2. Go to the Security credentials tab and create an Access Key. For “Use case,” select Other, and create the key. Copy the Access key and Secret access key—you will need these for the extension.
  3. Create a new S3 bucket with default settings. It is recommended to use a dedicated bucket for TypingMind backups.
  4. Open the bucket’s Permissions tab and edit the Bucket Policy. Paste the following JSON, replacing YOUR_BUCKET_NAME with your actual bucket name and YOUR_USER_ARN with the ARN of the user you created.
{
  "Version": "2012-10-17",
  "Statement":
    [
      {
        "Effect": "Allow",
        "Principal":
          { "AWS": "arn:aws:iam::<AWS Account ID>:user/<IAM username>" },
        "Action":
          [
            "s3:ListBucket",
            "s3:GetObject",
            "s3:PutObject",
            "s3:DeleteObject",
            "s3:ListBucketMultipartUploads",
            "s3:ListMultipartUploadParts",
            "s3:AbortMultipartUpload",
            "s3:GetBucketLocation",
            "s3:GetBucketVersioning",
            "s3:ListBucketVersions",
            "s3:DeleteObjectVersion",
          ],
        "Resource":
          [
            "arn:aws:s3:::<AWS bucket name>",
            "arn:aws:s3:::<AWS bucket name>/*",
          ],
      },
      {
        "Sid": "PreventSpecificFileDeletion",
        "Effect": "Deny",
        "Principal":
          { "AWS": "arn:aws:iam::<AWS Account ID>:user/<IAM username>" },
        "Action": "s3:DeleteObject",
        "Resource": "arn:aws:s3:::<AWS bucket name>/typingmind-backup.json",
      },
    ],
}

Update AWS Account ID, IAM username and AWS bucket name in the policy with your specific values.

  1. Open Bucket > Permissions > CORS
[
  {
    "AllowedHeaders": ["*"],
    "AllowedMethods": ["HEAD", "GET", "PUT", "POST", "DELETE"],
    "AllowedOrigins": ["https://*.hostname.com"],
    "ExposeHeaders":
      [
        "Access-Control-Allow-Origin",
        "ETag",
        "x-amz-server-side-encryption",
        "x-amz-request-id",
        "x-amz-id-2",
      ],
    "MaxAgeSeconds": 3000,
  },
]

If you are using typingmind cloud, use the below

[
  {
    "AllowedHeaders": ["*"],
    "AllowedMethods": ["HEAD", "GET", "PUT", "POST", "DELETE"],
    "AllowedOrigins": ["https://www.typingmind.com"],
    "ExposeHeaders":
      [
        "Access-Control-Allow-Origin",
        "ETag",
        "x-amz-server-side-encryption",
        "x-amz-request-id",
        "x-amz-id-2",
      ],
    "MaxAgeSeconds": 3000,
  },
]

Update “https://*.hostname.com” with your specific hostname in case you are self hosting Typingmind (e.g. https://chat.yourhostname.com). If you are using Typingmind cloud, hostname should be https://www.typingmind.com. This restricts executing S3 commands from only the specified hostname providing better security.

S3 compatible storage services setup

Cloudflare R2 provides S3 compatible API with a generous 10GB free storage per month. Refer How to setup Cloudflare R2 and use with this extension iDrive E2 provides S3 compatible API with a generous 10GB free storage per month. Refer How to setup iDrive E2 and use with this extension

🐛 Troubleshooting

Enable Logging

For troubleshooting, enable detailed logging:

  1. Startup Logging: Add ?log=true to your URL
  2. Runtime Logging: Toggle “Console Logging” in the config modal
  3. Check browser console for detailed sync information

Sync Issues Between Devices

Symptom: Different item counts between devices (e.g., Device 1 has 467 items, Device 2 has 376 items)

Root Cause: Local metadata corruption/inconsistency

Diagnosis:

  1. Open the Sync settings modal - check the “Sync Diagnostics” table
  2. Compare Local Items vs Cloud Items counts
  3. Look for mismatches between devices

Solutions (in order of preference):

Solution 1: Reset metadata on device with CORRECT data

Solution 2: Reset metadata on device with MISSING data

Solution 3: Complete sync reset (if Solutions 1-2 don’t work)

Prevention:

Using app in multiple devices simultaneously

The extension will work reliably only when one device is active at a time. So if you are facing issues, ensure the app is active only on one device at a time.

Warning

The extension encrypts the AWS credentials while its stored in the browser database. However, since the encryption key is still stored in plain text, sophisticated hackers who can get access to your browser data and could theoretically get access to your AWS credentials. So, be sure to provide minimum permissions to the AWS credentials. For Amazon S3, I have provided access policy above. However, for other S3 compatible providers, its up to you to setup proper access policies.

About me

I am a passionate developer dedicated to creating useful tools that can benefit the community. My goal is to distribute all of my projects as open source, enabling others to learn, contribute, and innovate together. If you appreciate my work and want to support my efforts, consider buying me a coffee. :heart:!

License

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