jollywhoppers.com
Bluesky app fork with some witchin' additions 💫
witchsky.app
bluesky
fork
client
xan.lol
1# Witchsky Social App 🧙 (alpha)
2
3Hey, witches! This is the codebase for the Witchsky app, based on [social.daniela.lol](https://github.com/kittibytess/deer-social) and prior [Bluesky](https://github.com/bluesky-social/social-app) forks.
4
5Get the app itself:
6
7- **Web: [witchsky.app](https://witchsky.app)**
8- **iOS: App Store [Soon™](https://cat-bounce.com/)?**
9- **Android: Play Store Soon! ([F-Droid repo](https://app.jolly.you/fdroid/repo) in the future?)**
10
11<!-- <a href="https://apps.obtainium.imranr.dev/redirect?r=obtainium://add/https://tangled.org/jollywhoppers.com/witchsky.app/">
12<img src="https://github.com/ImranR98/Obtainium/blob/main/assets/graphics/badge_obtainium.png?raw=true"
13alt="Get it on Obtainium" height="54" /></a> -->
14
15## Improvements on Bluesky
16
17- Cooler name (and kawaii logo)
18- Color scheme options and hue slider (defaults to Witchsky orange)
19- You can change "post" to any phrase you want in the UI
20- Choose between sharing witchsky.app or bsky.app links
21- Embed player works with [stream.place](https://stream.place/) links!
22- Open posts in PDSls and original pages of bridged posts
23- You can redraft posts
24- Better defaults (alt text required 😉 autoplay off 🫨)
25- More unique repost icons
26- Can download videos
27- Stay on a page when switching accounts
28- 'Mutuals' in place of 'Following' when relevant
29- No age assurance or blocks based on location
30- No push notifications (hopefully will be added later)
31- Kept as up-to-date as possible (sporadically unstable as a result)
32
33### Experiments
34
35These are all available as options in a sub-page of the app's settings.
36
37- Toggle go.bsky.app link proxying for analytics
38- Toggle to see posts in quotes through blocks and detachments
39- Toggle for buttons to show original fedi posts and in PDSls
40- Toggle to trust your own preferred verifiers (and to operate as one yourself)
41- Toggle to change Constellation instance for custom features
42- Toggle to disable the default app labeler(s)
43
44#### Tweaks
45
46- Toggle to turn non-bsky.social handles into clickable links
47- Toggle to combine reposts in horizontal carousels
48- Toggle the following feed fallback to the discover feed
49- Toggle displaying images in higher quality
50- Toggle to only show a single tab if only one feed is pinned
51- Toggle to prevent others from getting notified when you interact with their reposts
52- Toggle similar account recommendations
53- Toggle to make all user avatars square (like labelers)
54- Toggle for more square-ish UI (still slightly rounded)
55- Toggle to remove the composer prompt at the top of the Following & Discover feeds
56- Toggle between handle and DID in URLs and share links
57- Change post translation provider (between Google, Kagi, Papago, and LibreTranslate)
58- Use an OpenRouter API key for generating image alt text when posting
59
60#### Metrics
61
62You can completely disable the visiblity of all metrics individually, including the number of:
63
64- likes
65- reposts
66- quotes
67- saves
68- replies
69- followers
70- following
71- & who someone's followed by
72
73## Upcoming or wishful features
74
75- Better OpenGraph support for sharing profiles & posts (including videos & fixing quotes)
76- Selecting a custom AppView
77- Seeing past blocks in threads (the nuclear block in reply chains)
78- Configure the location used to determine regional labelers
79
80### TODO: Xan
81
82- [ ] Setup App Linking for Android (.well-known w/ app package fingerprint)
83- [ ] Fallback/email addresses to use witchsky.social in Automatic PDS detection
84- [ ] Change followed accounts [on onboarding](https://github.com/blacksky-algorithms/blacksky.community/commit/e36ee43efb4999f070860d7f70122e45b28c1e2b)
85- [ ] Join date & switch accounts in composer from a fork like [deer.aylac.top](https://github.com/ayla6/deer-social-test)
86- [ ] Visual replies indicator like the [Firmament userstyle](https://witchsky.app/profile/did:plc:jwhxcrf5uvl3vyw7nurecgt5/post/3m4rr3vzmak2a) (and likes?)
87- [ ] Put RunesSettings into separate subpages
88- [ ] After subpages for options, add [Outlinks page](https://witchsky.app/profile/did:plc:q7suwaz53ztc4mbiqyygbn43/post/3m5zjhhshic2g) &
89 - [ ] ShareMenuItems.tsx, ShareMenuItems.web.tsx
90- [ ] For profile meatball button, Open profile in PDSls & Open bridged OG fedi account page
91 - [ ] ProfileMenu.tsx
92- [ ] Witchsky PDS and .social site (list good songs containing 'bitch' in their titles for related site)
93
94### Even more wishful or far off
95
96- [ ] Collapse labels past a customizable number (from the same labeler?) into a labeler clip "(+)"
97- [ ] Submit releases to the Google Play Store and iOS App Store
98- [ ] Move from [Cloudflare Pages](https://pages.cloudflare.com/) to [wisp.place](https://wisp.place/) (needs serverless for embeds)
99- [ ] Move TOS and privacy policy to Jollywhoppers website
100- [ ] Ignore `!no-unauthenticated` labels
101- [ ] Material 3 Expressive theming on Android (Liquid **ass on iOS)
102
103## Development Resources
104
105This is a [React Native](https://reactnative.dev/) application, written in the TypeScript programming language. It builds on the `atproto` TypeScript packages (like [`@atproto/api`](https://www.npmjs.com/package/@atproto/api)), which are also open source, but in [a different git repository](https://github.com/bluesky-social/atproto).
106
107There is vestigial Go language source code (in `./bskyweb/`), for a web service that returns the React Native Web application in the social app deployment. However, it is not used in current Witchsky deployments.
108For Witchsky, the intended deployment is with a webserver that can serve static files, and reroute to `index.html` as needed. [Witchsky](https://witchsky.app) is currently hosted on [Cloudflare Pages](https://pages.cloudflare.com/).
109
110The [Build Instructions](./docs/build.md) are a good place to get started with the app itself. If you use nix (and especially direnv) then `flake.nix` will get you a working environment for the web version of the app.
111
112The Authenticated Transfer Protocol ("AT Protocol" or "atproto") is a decentralized social media protocol. You don't *need* to understand AT Protocol to work with this application, but it can help.
113You may wish to reference [resources linked in social-app](https://github.com/bluesky-social/social-app#development-resources). However, please don't harass the Bluesky team with issues or questions pertaining to Witchsky.
114
115Witchsky is a fork of the official Bluesky client, social-app. It encompasses a set of schemas and APIs built in the overall AT Protocol framework. The namespace for these "Lexicons" is `app.bsky.*`.
116
117## Contributions
118
119> Witchsky is a community fork, and we'd love to merge your PR!
120
121As a rule of thumb, the best features for Witchsky are those that have a disproportionately positive impact on the user experience compared to the maintenance overhead. Unlike some open source projects, since Witchsky is a soft fork, any features (patches) we add on top of upstream social-app need to be maintained. For example, a change to the way posts are composed may be very invasive, touching lots of code across the codebase. If upstream refactors this component, we will need to rewrite this feature to be compatible or drop it from the client.
122
123For this reason, only features that require changing only a small amount of code from upstream should be considered.
124
125Without an overriding motivation, opinionated features should exist behind a toggle that is not enabled by default. This allows Witchsky to cater to as many users as possible.
126
127### Guidelines
128
129- Check for existing issues before filing a new one please.
130- Open an issue and give some time for discussion before submitting a PR.
131 - This isn't strictly necessary, but the lead developers would love to give their thoughts and scope out your willingness to maintain the feature before you write it.
132- Stay away from PRs like...
133 - Changing "Quote" to "Bitch."
134 - Refactoring the codebase, e.g., to replace React Query with Redux Toolkit, etc.
135- Include a new toggle and preference for your feature.
136
137If we don't merge your PR for whatever reason, you are welcome to fork and/or self-host:
138
139## Forking guidelines
140
141Just like social-app, you have our blessing 🪄✨ to fork this application! However, it's very important to make it clear to users when you're giving them a fork.
142
143Please be sure to:
144
145- Change all branding in the repository and UI to clearly differentiate from Witchsky.
146- Change any support links (feedback, email, terms of service, issue tracker, etc) to your own systems.
147
148## Self hosting & personal builds
149
150Self hosting is great! It is our intention that Witchsky is easy to self host and build on your own. If you host your own instance of Witchsky, or make your own builds, please make some level of effort to clarify that it is not an "official" build or instance. This can be in the form of a different domain or branding, but can also be as simple as not advertising your hosted instance or builds as "official" releases.
151
152## Security disclosures
153
154If you discover any security issues, please privately disclose them to [xan.lol](https://xan.lol/).
155If the issue pertains to infastructure, code, or systems outside the scope of Witchsky, please refer to the [disclosure guidelines on social-app](https://github.com/bluesky-social/social-app#security-disclosures) if it is hosted by Bluesky PBC. Otherwise, reference the security policy of that system as applicable <3
156
157## License (MIT)
158
159See [./LICENSE](./LICENSE) for the full license.
160
161Bluesky Social PBC has committed to a software patent non-aggression pledge. For details see [the original announcement](https://bsky.social/about/blog/10-01-2025-patent-pledge).
162
163## P.S.
164
165We ❤️ you and all of the ways you support us. Thank you for making Bluesky & Witchsky so great! ^.^