search

marcomaroni-github / twitter-to-bluesky

Import all tweets exported from X/Twitter to a Bluesky account.
Other
499 stars 35 forks source link

readme

X/Twitter To Bluesky

Import all tweets exported from X/Twitter to a Bluesky account.

They use the official archive export file format from X/Twitter, this utility reads the archive from the local disk and using the official Bluesky Typescript SDK imports the tweets into the configured Bluesky account.

An example of an account used to import X/Twitter archive

⚠️ We recommend creating a specific account to test the import and not using your main Bluesky account ⚠️

Which tweets are NOT imported

Prerequisite

Breaking changes from version < 0.10

Getting started

Before everything else, you need to request your Twitter archive. You can do this by following the instructions on the official Twitter support page: Requesting your Twitter archive. This process may take a few days, and you will receive an email with a link to download the archive once it's ready.

The program requires the Node.js runtime to be explicitly installed on your machine. You can check if you have it installed by running node -v in your terminal/console application. If you don't have it installed, you can download and install it from the official website: Node.js

Once you have Node.js installed, and if you don't know what git clone means (don't go look it up, it's not important), you can download the source code as a zip file from this GitHub repository and extract it to a folder on your computer. Pick the latest release.

Navigate to the folder where you extracted the source code and open a terminal/console application in that folder. You can do this by typing cmd in the address bar of the folder in Windows or by right-clicking in the folder and selecting "Open in Terminal" in MacOS.

In the project folder now run npm install. This will download and install all the modules required by the module to run.

Run the program

You can run the program using command line arguments or environment variables. We recommend using command line arguments to start with, as they are easier to understand and manage.

Mind that the program may have to run for a long time, potentially for several days, if you have a lot of tweets to import. It is recommended to run the program on a computer that you can leave running for a long time without interruptions. Once you hit your daily limit of posts, the program will display the time when the limit resets and wait until your limit is reset before continuing. You can put your computer to sleep while waiting.

If you have interrupted the program, you can restart it, and it will continue from where it left off. That information is stored in the "tweets_mapping.json" file in the project folder. Don't delete that file unless you want to start the import from scratch or import a different archive.

We highly recommend trying to simulate the import first and import a small range of tweets, using the additional parameters documented below.

Using environment variables

You can also set the required parameters using environment variables or a .env file.

Create an .env file in the project folder where you set the following variables or set those in your environment:

Additionally you can set these environment variables to customize behavior:

Example of a .env file:

BLUESKY_USERNAME=test.bsky.social
BLUESKY_PASSWORD=pwd123
ARCHIVE_FOLDER=C:/Temp/twitter-archive
TWITTER_HANDLES=marcomaroni,user
IGNORE_VIDEO_ERRORS=1

Then you can run the script with npm start or npm run start_log to write an import.log file.

Using command line arguments

To start the program, use: npm run start -- -- [args] where [args] are the arguments you want to pass to the program that are documented below. The double double-dashes may look a bit odd, but they are necessary to pass arguments to the program. (Not our choice, sorry!)

Required Arguments

You need to gather your Twitter archive and create a Bluesky account before running the program.

You must provide these arguments for the program to work:

Optional Arguments

These arguments are optional and help customize the import:

Examples when running on Windows

Assuming you stored the Twitter archive in C:\Temp\twitter-archive and you want to import tweets from two Twitter handles:

npm run start -- -- --archive-folder C:\Temp\twitter-archive --bluesky-username test.bsky.social --bluesky-password pwd123 --twitter-handles sampleuser1 sampleuser2

Examples when running on MacOS or Linux

Assuming you stored the Twitter archive in your home folder and you want to import tweets from one Twitter handle:

npm run start -- -- --archive-folder ~/twitter-archive --bluesky-username test.bsky.social --bluesky-password pwd123 --twitter-handles sampleuser1

Common issues and resolutions

No matter what you seem to do, you get the error "Missing required arguments: archive-folder, bluesky-username, bluesky-password"

See issue #77 for more details.

In this case, you may need to change the command slightly. Instead of npm run start -- -- [args], you would use node app.js [args] instead. For example:

node app.js --archive-folder ~/twitter-archive --bluesky-username test.bsky.social --bluesky-password passwd123 --twitter-handles sampleuser1

Imported tweets appear as recent posts on your BlueSky timeline

Some of the tweets may show up as recent posts on your BlueSky timeline during the import process. This seems to be a bug with how BlueSky handles the recently imported tweets. They don't show up in other people's timelines, and their date gets corrected in a couple of minutes. No need to worry about this. Issue #97.

You get an error like "XRPCError: missing jobId" and your Twitter account has videos

See issue #94 for more details.

In this case, you may have videos that exceed the 60 second limit on Bluesky or have other video upload issues. You would need to add the arguments --ignore-video-errors and --video-upload-retries to import the remaining tweets, bypassing the offending videos. Example:

npm run start -- -- --archive-folder ~/twitter-archive --bluesky-username test.bsky.social --bluesky-password pwd123 --twitter-handles sampleuser1 --ignore-video-errors --video-upload-retries 5

Dev Container

Add the directory to your exported data

"mounts": [
    "source=PATH/TO/LOCAL,target=/workspaces/twitter-to-bluesky/data,type=bind,consistency=cached"
]

Use

 node app.js --archive-folder

instead of npm start

License

"Twitter To Bluesky" is published under the MIT license.

Copyright 2024 Marco Maroni

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.