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 V4.2

A comprehensive cloud backup and sync extension for TypingMind that automatically backs up and synchronizes your entire TypingMind data with multiple cloud storage providers including AWS S3, S3-compatible services, and Google Drive.

✨ Key Features

☁️ Multi-Provider Support

🔄 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/cloudsync.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, the extension will show an alert prompting you to configure these settings. The extension needs these credentials to function.

Storage Provider Selection

The extension supports multiple cloud storage providers. Select your preferred provider from the Storage Type dropdown:

Configuration Fields

The required fields depend on your chosen storage provider:

For S3 / S3-Compatible Storage (marked with *):

For Google Drive:

Common 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.

For S3/S3-Compatible Storage:

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

For Google Drive:

https://your-typingmind-url.com/?storagetype=googleDrive&googleclientid=your-client-id&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 from Earlier Versions

Migration to V4+

V4 introduced major architectural changes including multi-provider support and attachment handling. However, V4 is fully backward compatible with V3 backups and cloud data structures.

What’s New in V4.2

What to Expect During Migration from V3 to V4+

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

Migration to V3+ (from V1/V2)

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

What to Expect During Migration from V1/V2 to V3+

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: Load the extension URL: https://itcon-pty-au.github.io/typingmind-cloud-backup/cloudsync.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+/V4+ File Structure

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

Note: This structure applies to S3 and S3-compatible storage. Google Drive uses a similar logical structure but with Google Drive’s folder system.

Any other files or folders at the root of your bucket are no longer used by V3+/V4+ 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

The extension supports multiple cloud storage providers. Choose the one that best fits your needs:

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

Google Cloud Storage (part of GCP) is another S3 compatible storage, compatible with this extension. Please refer to the manual for setup instructions.

Google Drive

Google Drive can be used as a cloud storage provider using Google’s native API.

Setup Steps:

  1. Go to the Google Cloud Console
  2. Create a new project or select an existing one
  3. Enable the Google Drive API for your project:
    • Navigate to “APIs & Services” > “Library”
    • Search for “Google Drive API” and enable it
  4. Create OAuth 2.0 credentials:
    • Go to “APIs & Services” > “Credentials”
    • Click “Create Credentials” > “OAuth client ID”
    • Choose “Web application” as the application type
    • Add your TypingMind URL to “Authorized JavaScript origins” (e.g., https://www.typingmind.com or your self-hosted URL)
    • Add your TypingMind URL to “Authorized redirect URIs”
  5. Copy the Client ID and use it in the extension configuration
  6. In the extension’s sync modal, select “Google Drive” as the storage type
  7. Enter your Client ID and encryption key, then click “Authorize Google Drive”
  8. Complete the OAuth flow to grant the extension access to your Google Drive

Note: The extension creates a dedicated folder in your Google Drive for TypingMind backups and maintains the same logical structure as S3 storage.

🐛 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.