Guide · Open source
How to use social-app: clone, build and fork the Bluesky code
Updated · written with AI from the project's own documentation and checked against our catalogue data
social-app is the source code repository for the Bluesky Social app, which runs on the web, iOS and Android. It is written in TypeScript with React Native, so one codebase produces all three versions. This guide shows developers how to get the code, what the repository contains, and what rules apply if you want to fork or contribute.
Blueskybluesky-social/social-app · ★ 18.4k · MIT Install options & downloads Quick start
- 1Clone the repository. Run git clone https://github.com/bluesky-social/social-app to download the source.
- 2Read the build instructions. Open docs/build.md in the repository, which the README names as the starting point for building the app.
- 3Explore the code. Look at the React Native TypeScript app and the ./bskyweb/ Go service to see how one codebase serves web and mobile.
- 4Check the licence files. Read LICENSE, ASSETS.md and NOTICE.md to see which files the MIT license does not cover.
- 5Discuss before contributing. Search existing issues and open a new one for discussion before you write a pull request.
- 6Fork responsibly. If you fork, rebrand the app, replace support and analytics links, and swap out the restricted assets.
What social-app is and who it is for
social-app is the code behind the Bluesky Social app. The README says the app is built with React Native and TypeScript so one codebase can target Web, iOS and Android. It uses the AT Protocol (atproto), an open decentralized social media protocol.
This repository is a good fit for developers who want to read how a production React Native app targets web and mobile together, or who are studying a real client for the AT Protocol. It is not the place to go if you only want to use Bluesky.
- Web: bsky.app
- iOS: the App Store listing linked in the README
- Android: the Play Store listing linked in the README
Clone the repository
The README lists one install step: clone the repository with git. The source lists no other prerequisites, so check the build instructions linked in the README before you start work on the app itself.
The README points to docs/build.md as the place to get started with building the app.
git clone https://github.com/bluesky-social/social-appUnderstand the layout of the codebase
The app is a React Native application written in TypeScript. It builds on the atproto TypeScript packages, such as @atproto/api, which live in a separate git repository.
The repository also contains a small amount of Go code in ./bskyweb/, which is a web service that returns the React Native Web application. The API schemas use the app.bsky.* namespace, called Lexicons.
- ./bskyweb/: Go web service that serves the React Native Web app
- assets/illustrations/ and assets/icons/: artwork and icon files covered by separate rules
- ASSETS.md: explains which files are not covered by the MIT license
- NOTICE.md: third-party attribution notices
- LICENSE: the MIT license for the source code
Learn the AT Protocol basics if you need them
You do not need to understand AT Protocol to work with this application, according to the README. It can help, though. The README links to the overview and guides on atproto.com, the protocol specifications, and the GitHub Discussions in the atproto repository, which it describes as a good place to ask questions.
- Overview and Guides: atproto.com/guides/overview
- Protocol Specifications: atproto.com/specs/atp
- GitHub Discussions: github.com/bluesky-social/atproto/discussions
Follow the contribution rules before opening a pull request
The maintainers prioritise high-quality issues and pull requests. The README says they may not respond to an issue or PR, may close one without much feedback, and will not provide support for build issues.
Open an issue and allow time for discussion before you submit a PR. Check for existing issues first. The README asks contributors to avoid cosmetic renames, large refactors and new features without prior discussion.
- Search existing issues before filing a new one
- Open an issue and wait for discussion before sending a PR
- Avoid renaming UI terms, broad refactors and unapproved new features
Fork the app safely
The README gives permission to fork the application, but asks forks to be clearly distinct from Bluesky. Forks must change branding, support links and analytics or error-collection systems.
Some files are not covered by the MIT license. The README names the landing-screen illustration in assets/illustrations/, the icons in assets/icons/, and the Bluesky logo, app icons and brand assets. Read ASSETS.md before you ship a fork.
- Change all branding in the repository and UI
- Point support links (feedback, email, terms of service) to your own systems
- Replace analytics and error-collection systems with your own
- Replace the illustration in assets/illustrations/
- Source your own UI icons instead of using assets/icons/
- Replace the Bluesky logo, app icons and other brand assets
- Read ASSETS.md and NOTICE.md before shipping
What people use it for
- Studying how a production React Native app shares one TypeScript codebase across web, iOS and Android
- Reading a real-world client built on the AT Protocol and its @atproto/api package
- Building a fork of the app for your own community, after following the forking guidelines
- Sending a well-scoped bug fix or improvement after discussing it in an issue
Frequently asked questions
Is social-app free to use?
The repository is released under the MIT license, which covers the source code. The README says some images, icons, fonts and brand assets are not covered and are carved out in ASSETS.md, so check that file before reusing anything beyond the code.
How do I install social-app?
The README gives one install command: git clone https://github.com/bluesky-social/social-app. For building the app, the README points to docs/build.md. It does not list any other prerequisites.
Where do I download the Bluesky app instead of building it?
The README says the public apps are at bsky.app for the web, the App Store for iOS and the Play Store for Android. Use those links if you only want to use Bluesky.
Does social-app support build problems?
No. The README states the maintainers will not provide support for build issues. Search existing issues first, since your question may already have an answer.
Do I need to understand AT Protocol to use this code?
No, according to the README. It says you do not need to understand AT Protocol to work with the app, but the linked guides, specifications and GitHub Discussions can help.
How does social-app compare to Mastodon, Element or Lens?
This source does not compare them. Mastodon, Element and Lens are listed as comparable projects in our analysis, but this README covers only the Bluesky app and its AT Protocol base, so review each project on its own terms.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
social-app suits developers who want to study or fork a production React Native client for the AT Protocol, and who are willing to follow the contribution and asset rules. It is not suited to people who just want to use Bluesky, or anyone who needs help troubleshooting a build, since the README offers no build support.
Install options & downloads