forked from
jollywhoppers.com/witchsky.app
Bluesky app fork with some witchin' additions 💫
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)?)**
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- Posts are called Skeets (may let you choose in the future)
20- Choose between sharing witchsky.app or bsky.app links
21- Embed player works with [stream.place](https://stream.place/) links!
22- Open skeets in PDSls and original pages of bridged posts
23- You can redraft skeets
24- Better defaults (alt text required 😉 autoplay off 🫨)
25- More unique repost icons
26- Can download videos
27- 'Mutuals' in place of 'Following' when relevant
28- No push notifications (hopefully will be added later)
29- Kept as up-to-date as possible (sporadically unstable as a result)
30
31### Experiments
32
33These are all available as options in a sub-page of the app's settings.
34
35- Toggle go.bsky.app link proxying for analytics
36- Toggle to see skeets in quotes through blocks and detachments
37- Toggle for buttons to show original fedi posts and in PDSls
38- Toggle to trust your own preferred verifiers (and to operate as one yourself)
39- Toggle to change Constellation instance for custom features
40- Toggle to disable the default app labeler(s)
41
42#### Tweaks
43
44- Toggle to turn non-bsky.social handles into clickable links
45- Toggle to combine reskeets in horizontal carousels
46- Toggle the following feed fallback to the discover feed
47- Toggle displaying images in higher quality
48- Toggle to only show a single tab if only one feed is pinned
49- Toggle to prevent others from getting notified when you interact with their reskeets
50- Toggle similar account recommendations
51- Toggle to make all user avatars square (like labelers)
52- Toggle for more square-ish UI (still slightly rounded)
53- Toggle to remove the composer prompt at the top of the Following & Discover feeds
54- Change post translation provider (between Google, Kagi, Papago, and LibreTranslate)
55
56#### Metrics
57
58You can completely disable the visiblity of all metrics individually, including the number of:
59
60- likes
61- reskeets
62- quotes
63- saves
64- replies
65- followers
66- following
67- & who someone's followed by
68
69## Upcoming or wishful features
70
71- Better OpenGraph support for sharing profiles & skeets (including videos & fixing quotes)
72- Selecting a custom AppView
73- Seeing past blocks in threads (the nuclear block in reply chains)
74- Configure the location used to determine regional labelers
75
76### TODO: Xan
77
78- [ ] Setup App Linking for Android (.well-known w/ app package fingerprint)
79- [ ] Fallback/email addresses to use witchsky.social in Automatic PDS detection
80- [ ] Change followed accounts [on onboarding](https://github.com/blacksky-algorithms/blacksky.community/commit/e36ee43efb4999f070860d7f70122e45b28c1e2b)
81- [ ] Join date & switch accounts in composer from a fork like [deer.aylac.top](https://github.com/ayla6/deer-social-test)
82- [ ] Visual replies indicator like the [Firmament userstyle](https://witchsky.app/profile/did:plc:jwhxcrf5uvl3vyw7nurecgt5/post/3m4rr3vzmak2a) (and likes?)
83- [ ] Put DeerSettings into separate subpages
84- [ ] After subpages for options, add [Outlinks page](https://witchsky.app/profile/did:plc:q7suwaz53ztc4mbiqyygbn43/post/3m5zjhhshic2g) &
85 - [ ] ShareMenuItems.tsx, ShareMenuItems.web.tsx
86- [ ] For profile meatball button, Open profile in PDSls & Open bridged OG fedi account page
87 - [ ] ProfileMenu.tsx
88- [ ] Witchsky PDS and .social site (list good songs containing 'bitch' in their titles for related site)
89
90### Even more wishful or far off
91
92- [ ] Collapse labels past a customizable number (from the same labeler?) into a labeler clip "(+)"
93- [ ] Submit releases to the Google Play Store and iOS App Store
94- [ ] Move from [Cloudflare Pages](https://pages.cloudflare.com/) to [wisp.place](https://wisp.place/) (needs serverless for embeds)
95- [ ] Toggle between handle and DID in share links
96- [ ] Move TOS and privacy policy to Jollywhoppers website
97- [ ] Ignore `!no-unauthenticated` labels
98- [ ] Material 3 Expressive theming on Android (Liquid **ass on iOS)
99
100## Development Resources
101
102This 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).
103
104There 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.
105For 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/).
106
107The [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.
108
109The 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.
110You 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.
111
112Witchsky 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.*`.
113
114## Contributions
115
116> Witchsky is a community fork, and we'd love to merge your PR!
117
118As 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 skeets 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.
119
120For this reason, only features that require changing only a small amount of code from upstream should be considered.
121
122Without 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.
123
124### Guidelines
125
126- Check for existing issues before filing a new one please.
127- Open an issue and give some time for discussion before submitting a PR.
128 - 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.
129- Stay away from PRs like...
130 - Changing "Quote" to "Bitch."
131 - Refactoring the codebase, e.g., to replace React Query with Redux Toolkit, etc.
132- Include a new toggle and preference for your feature.
133
134If we don't merge your PR for whatever reason, you are welcome to fork and/or self-host:
135
136## Forking guidelines
137
138Just 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.
139
140Please be sure to:
141
142- Change all branding in the repository and UI to clearly differentiate from Witchsky.
143- Change any support links (feedback, email, terms of service, issue tracker, etc) to your own systems.
144
145## Self hosting & personal builds
146
147Self 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.
148
149## Security disclosures
150
151If you discover any security issues, please privately disclose them to [xan.lol](https://xan.lol/).
152If 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
153
154## License (MIT)
155
156See [./LICENSE](./LICENSE) for the full license.
157
158Bluesky 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).
159
160## P.S.
161
162We ❤️ you and all of the ways you support us. Thank you for making Bluesky & Witchsky so great! ^.^