oppi.li
forked from
jollywhoppers.com/witchsky.app
Bluesky app fork with some witchin' additions 💫
1# Build instructions
2
3## Running Web App
4
5- `yarn`
6- `yarn web`
7
8You're all set!
9
10## iOS/Android Build
11
12### Native Environment Setup
13
14This is NOT required when developing for web.
15
16- Set up your environment [using the expo instructions](https://docs.expo.dev/guides/local-app-development/).
17 - make sure that the JAVA_HOME points to the zulu-17 directory in your `.zshrc` or `.bashrc` file: `export JAVA_HOME=/Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home`. DO NOT use another JDK or you will encounter build errors.
18- If you're running macOS, make sure you are running the correct versions of Ruby and Cocoapods:-
19 - If you are using Apple Silicon and this is the first time you are building for RN 0.74+, you may need to run:
20 - `arch -arm64 brew install llvm`
21 - `sudo gem install ffi`
22 - Check if you've installed Cocoapods through `homebrew`. If you have, remove it:
23 - `brew info cocoapods`
24 - If output says `Installed`:
25 - `brew remove cocoapods`
26 - If you have not installed `rbenv`:
27 - `brew install rbenv`
28 - `rbenv install 2.7.6`
29 - `rbenv global 2.7.6`
30 - Add `eval "$(rbenv init - zsh)"` to your `~/.zshrc`
31 - From inside the project directory:
32 - `bundler install` (this will install Cocoapods)
33- After initial setup:
34 - Copy `google-services.json.example` to `google-services.json` or provide your own `google-services.json`. (A real firebase project is NOT required)
35 - `npx expo prebuild` -> you will also need to run this anytime `app.json` or native `package.json` deps change
36
37### Running the Native App
38
39- iOS: `yarn ios`
40 - Xcode must be installed for this to run.
41 - A simulator must be preconfigured in Xcode settings.
42 - if no iOS versions are available, install the iOS runtime at `Xcode > Settings > Platforms`.
43 - if the simulator download keeps failing you can download it from the developer website.
44 - [Apple Developer](https://developer.apple.com/download/all/?q=Simulator%20Runtime)
45 - `xcode-select -s /Applications/Xcode.app`
46 - `xcodebuild -runFirstLaunch`
47 - `xcrun simctl runtime add "~/Downloads/iOS_17.4_Simulator_Runtime.dmg"` (adapt the path to the downloaded file)
48 - In addition, ensure Xcode Command Line Tools are installed using `xcode-select --install`.
49 - Expo will require you to configure Xcode Signing. Follow the linked instructions. Error messages in Xcode related to the signing process can be safely ignored when installing on the iOS Simulator; Expo merely requires the profile to exist in order to install the app on the Simulator.
50 - Make sure you do have a certificate: open Xcode > Settings > Accounts > (sign-in) > Manage Certificates > + > Apple Development > Done.
51 - If you still encounter issues, try `rm -rf ios` before trying to build again (`yarn ios`)
52- Android: `yarn android`
53 - Install "Android Studio"
54 - Make sure you have the Android SDK installed (Android Studio > Tools > Android SDK).
55 - In "SDK Platforms": "Android x" (where x is Android's current version).
56 - In "SDK Tools": "Android SDK Build-Tools" and "Android Emulator" are required.
57 - Add `export ANDROID_HOME=/Users/<your_username>/Library/Android/sdk` to your `.zshrc` or `.bashrc` (and restart your terminal).
58 - Setup an emulator (Android Studio > Tools > Device Manager).
59- Web: `yarn web` (see the top of this file).
60
61After you do `yarn ios` and `yarn android` once, you can later just run `yarn web` and then press either `i` or `a` to open iOS and Android emulators respectively which is much faster. However, if you make native changes, you'll have to do `yarn prebuild -p ios` and `yarn prebuild -p android` and then `yarn ios` and `yarn android` again before you can continue with the same workflow.
62
63### Tips
64
65- Copy the `.env.example` to `.env` and fill in any necessary tokens. (The Sentry token is NOT required; see instructions below if you want to enable Sentry.)
66- To run on the device, add `--device` to the command (e.g. `yarn android --device`). To build in production mode (slower build, faster app), also add `--variant release` on Android or `--configuration Release` on iOS.
67- If you want to use Expo EAS on your own builds without ejecting from Expo, make sure to change the `owner` and `extra.eas.projectId` properties. If you do not have an Expo account, you may remove these properties.
68- `npx react-native info` Checks what has been installed.
69- If the Android simulator frequently hangs or is very sluggish, [bump its memory limit](https://stackoverflow.com/a/40068396)
70- The Android simulator won't be able to access localhost services unless you run `adb reverse tcp:{PORT} tcp:{PORT}`
71 - For instance, the locally-hosted dev-wallet will need `adb reverse tcp:3001 tcp:3001`
72- For some reason, the typescript compiler chokes on platform-specific files (e.g. `foo.native.ts`) but only when compiling for Web thus far. Therefore we always have one version of the file that doesn't use a platform specifier, and that should be the Web version. ([More info](https://stackoverflow.com/questions/44001050/platform-specific-import-component-in-react-native-with-typescript).)
73
74### Running E2E Tests
75
76- Start in various console tabs:
77 - `yarn e2e:mock-server`
78 - `yarn e2e:start`
79- Run once: `yarn e2e:build`
80- Each test run: `yarn e2e:run`
81
82### Adding Sentry
83
84Adding Sentry is NOT required. You can keep `SENTRY_AUTH_TOKEN=` in `.env` which will build the app without Sentry.
85
86However, if you're a part of the Bluesky team and want to enable Sentry, fill in `SENTRY_AUTH_TOKEN` in your `.env`. It can be created on the Sentry dashboard using [these instructions](https://docs.expo.dev/guides/using-sentry/#sign-up-for-a-sentry-account-and-create-a-project).
87
88If you change `SENTRY_AUTH_TOKEN`, you need to do `yarn prebuild` before running `yarn ios` or `yarn android` again.
89
90### Adding bitdrift
91
92Adding bitdrift is NOT required. You can keep `EXPO_PUBLIC_BITDRIFT_API_KEY=` in `.env` which will avoid initializing bitdrift during startup.
93
94However, if you're a part of the Bluesky team and want to enable bitdrift, fill in `EXPO_PUBLIC_BITDRIFT_API_KEY` in your `.env` to enable bitdrift.
95
96### Adding and Updating Locales
97
98- `yarn intl:build` -> you will also need to run this anytime `./src/locale/{locale}/messages.po` change
99
100## Running the Backend Locally
101
102This is NOT required for app development but if you also want to develop the Bluesky *backend* locally too, you'll need this.
103
104- Start the dev servers
105 - `git clone git@github.com:bluesky-social/atproto.git`
106 - `cd atproto`
107 - `brew install pnpm`
108 - optional: `brew install jq`
109 - `pnpm i`
110 - `pnpm build`
111 - Start the docker daemon (on MacOS this entails starting the Docker Desktop app)
112 - Launch a Postgres database on port 5432
113 - `cd packages/dev-env && pnpm start`
114
115Then, when logging in or creating an account, point it to the localhost port of the devserver.
116
117## Go-Server Build
118
119The Go server in this repository is only used for serving the web app in production. Usually you won't need to touch it.
120
121### Prerequisites
122
123- [Go](https://go.dev/)
124- [Yarn](https://yarnpkg.com/)
125
126### Steps
127
128To run the build with Go, use staging credentials, your own, or any other account you create.
129
130```
131cd social-app
132yarn && yarn build-web
133cd bskyweb/
134go mod tidy
135go build -v -tags timetzdata -o bskyweb ./cmd/bskyweb
136./bskyweb serve --appview-host=https://public.api.bsky.app
137```
138
139On build success, access the application at [http://localhost:8100/](http://localhost:8100/). Subsequent changes require re-running the above steps in order to be reflected.
140
141## Various notes
142
143### Debugging
144
145- Note that since 0.70, debugging using the old debugger (which shows up using CMD+D) doesn't work anymore. Follow the instructions below to debug the code: https://reactnative.dev/docs/next/hermes#debugging-js-on-hermes-using-google-chromes-devtools
146
147### Developer Menu
148
149To open the [Developer Menu](https://docs.expo.dev/debugging/tools/#developer-menu) on an `expo-dev-client` app you can do the following:
150
151- Android Device: Shake the device vertically, or if your device is connected via USB, run adb shell input keyevent 82 in your terminal
152- Android Emulator: Either press Cmd ⌘ + m or Ctrl + m or run adb shell input keyevent 82 in your terminal
153- iOS Device: Shake the device, or touch 3 fingers to the screen
154- iOS Simulator: Press Ctrl + Cmd ⌘ + z on a Mac in the emulator to simulate the shake gesture or press Cmd ⌘ + d
155
156### Running E2E Tests
157
158See [testing.md](./testing.md).
159
160### Polyfills
161
162`./platform/polyfills.*.ts` adds polyfills to the environment. Currently, this includes:
163
164- TextEncoder / TextDecoder
165- react-native-url-polyfill
166- Array#findLast (on web)
167
168### Sentry sourcemaps
169
170Sourcemaps should automatically be updated when a signed build is created using `eas build` and published using `eas submit` due to the postPublish hook setup in `app.json`. However, if an update is created and published OTA using `eas update`, we need to take the following steps to upload sourcemaps to Sentry:
171
172- Run eas update. This will generate a dist folder in your project root, which contains your JavaScript bundles and source maps. This command will also output the 'Android update ID' and 'iOS update ID' that we'll need in the next step.
173- Copy or rename the bundle names in the `dist/bundles` folder to match `index.android.bundle` (Android) or `main.jsbundle` (iOS).
174- Next, you can use the Sentry CLI to upload your bundles and source maps:
175 - release name should be set to `${bundleIdentifier}@${version}+${buildNumber}` (iOS) or `${androidPackage}@${version}+${versionCode}` (Android), so for example `com.domain.myapp@1.0.0+1`.
176 - `dist` should be set to the Update ID that `eas update` generated.
177- Command for Android:
178 `node_modules/@sentry/cli/bin/sentry-cli releases \
179files <release name> \
180upload-sourcemaps \
181--dist <Android Update ID> \
182--rewrite \
183dist/bundles/index.android.bundle dist/bundles/android-<hash>.map`
184- Command for iOS:
185 `node_modules/@sentry/cli/bin/sentry-cli releases \
186files <release name> \
187upload-sourcemaps \
188--dist <iOS Update ID> \
189--rewrite \
190dist/bundles/main.jsbundle dist/bundles/ios-<hash>.map`
191
192### OTA updates
193
194To create OTA updates, run `eas update` along with the `--branch` flag to indicate which branch you want to push the update to, and the `--message` flag to indicate a message for yourself and your team that shows up on https://expo.dev. All the channels (which make up the options for the `--branch` flag) are given in `eas.json`. [See more here](https://docs.expo.dev/eas-update/getting-started/)
195
196The clients which can receive an OTA update are governed by the `runtimeVersion` property in `app.json`. Right now, it is set so that only apps with the same `appVersion` (same as `version` property in `app.json`) can receive the update and install it. However, we can manually set `"runtimeVersion": "1.34.0"` or anything along those lines as well. This is useful if very little native code changes from update to update. If we are manually setting `runtimeVersion`, we should increment the version each time the native code is changed. [See more here](https://docs.expo.dev/eas-update/runtime-versions/)