Skip to content

Commit 369b1f5

Browse files
codinsonncodinsonn
committed
feat: Add README.md next to just README.mdx
1 parent 2145ad4 commit 369b1f5

1 file changed

Lines changed: 338 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 338 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,338 @@
1+
# codinsonn.dev - Personal Website
2+
3+
<p>
4+
<a href="https://codinsonn.dev">
5+
<img alt="Built with Next.js" longdesc="Built with Next.js" src="https://img.shields.io/badge/Next-black?style=for-the-badge&logo=next.js&logoColor=white" />
6+
</a>
7+
<a href="https://codinsonn.dev">
8+
<img alt="Built with Vercel Deployments" longdesc="Built with Vercel Deployments" src="https://img.shields.io/badge/vercel-%23000000.svg?style=for-the-badge&logo=vercel&logoColor=white" />
9+
</a>
10+
<a href="https://main--63e8ae7f443d84f16518d4e5.chromatic.com/?path=/story/readme-md--page">
11+
<img alt="Test in Expo GO" longdesc="Test in Expo GO" src="https://img.shields.io/badge/expo-1C1E24?style=for-the-badge&logo=expo&logoColor=#D04A37" />
12+
</a>
13+
<a href="https://main--63e8ae7f443d84f16518d4e5.chromatic.com/?path=/story/readme-md--page">
14+
<img alt="Docs with Storybook" longdesc="Documentated with Storybook" src="https://img.shields.io/badge/-Storybook-FF4785?style=for-the-badge&logo=storybook&logoColor=fff" />
15+
</a>
16+
</p>
17+
18+
> This project was bootstrapped with [Aetherspace](https://github.com/sponsors/codinsonn), the Evergreen repo setup for all your full-stack cross platform app development needs \{...💚\} Enabling the project to be built for Web, iOS, Android, PWA, Static, SSR, API routes and GraphQL all at once 👇 ... while also documenting your code automatically with Storybook.
19+
20+
### Getting started ⚡️
21+
22+
Install packages: `yarn install`
23+
24+
Run on web & mobile: `yarn dev`
25+
26+
Run with Storybook docs: `yarn dev:docs`
27+
28+
---
29+
30+
<details>
31+
<summary><b>✅ Aetherspace, GREEN stack & template benefits? 🚀</b></summary>
32+
33+
---
34+
35+
# Aetherspace - GREEN stack starter template for cross platform React app development
36+
37+
> 🐦 [Anouncement post](https://dev.to/codinsonn/how-to-compete-with-elons-twitter-a-dev-perspective-4j64)
38+
> ⚡️ [Quickstart example](https://main--63e8ae7f443d84f16518d4e5.chromatic.com/?path=/story/aetherspace-quickstart--page)
39+
40+
### Table of contents
41+
42+
💚 - [What is the GREEN stack?](#what-is-the-green-stack)
43+
🚀 - [What is Aetherspace?](#what-is-aetherspace)
44+
🤖 - [Why start with a turbo/monorepo?](#why-turborepo)
45+
📁 - [File structure and installing new packages.](#package-management)
46+
👾 - [Benefits and next steps.](#benefits-next-steps)
47+
🤷‍♂️ - [When _not_ to use the GREEN stack.](#when-not-to-use-green-stack)
48+
📚 - [Relevant Docs.](#relevant-docs)
49+
50+
## What the hell is the GREEN stack? 💚 <a name="what-is-the-green-stack"></a>
51+
52+
In short GREEN stands for these 5 core technologies:
53+
54+
- **G**raphQL for typed and self documenting APIs
55+
- **R**eact & React-Native for write-once UI
56+
- **E**vergreen components (extendable, themable, with docs, types & tests)
57+
- **E**xpo for easy mobile development, deployment and testing
58+
- **N**ext.js for web, SEO, Static & Server rendering, API & Web-Vitals
59+
60+
The core idea is writing your app code or features just once with Typescript and React-Native, yet make it available on any platform or device without double implementations or the need for different development teams.
61+
62+
## How does 'Aetherspace' help, exactly? 🚀 <a name="what-is-aetherspace"></a>
63+
64+
> Think of it as Unity for React Apps. Just like Unity aims to make cross console game development a lot easier for (indie) game devs, Aetherspace's setup for the GREEN stack aims to do the same for cross-platform app development.
65+
66+
### Core concepts
67+
68+
- Cross-platform from the start
69+
- Take what works, make it better
70+
- Single sources of truth
71+
- Write once, use anywhere
72+
- Documentation drives adoption
73+
74+
#### It helps you move fast, save time and deliver more
75+
76+
Aetherspace is an opinionated framework that fills in the gaps of working and building with the GREEN stack:
77+
78+
- How should I handle responsive design?
79+
- How do I avoid web layout shift when react-native styling does not support media queries or classnames?
80+
- How can I expose / read public env vars across multiple platforms?
81+
- How do I take advantage of optimisations like `next/image` on web when that's not available in React-Native?
82+
- What's the best way to style and animate my UI elements for both web and mobile?
83+
84+
Just to name a few.
85+
86+
While the stack itself is very powerful, figuring out how to get set up and do certain things in a write-once way can be frustrating and time consuming. To save you time figuring it all out on your own, _Aetherspace_ contains a bunch of packages, utils and best-practices to set you up for a quick and easy ride to cross-platform success.
87+
88+
## But why start with a turbo/monorepo? 🤖 <a name="why-turborepo"></a>
89+
90+
One annoying thing about figuring this stack out on your own is when packages you're using require custom configs for babel, webpack or otherwise. With Expo and Next.js, it often happens that updating e.g. a single `babel.config.js` used for both Expo and Next.js will fix usage on either, but then break the other.
91+
92+
Using a monorepo with different entry points for Next.js and Expo allows us to keep configs more separate, and therefore allow more confident updating of packages and configs without accidentally breaking other platforms.
93+
94+
In this starter template, we've opted to use turborepo with yarn workspaces. We'll list some basics in the next section, but for a deeper understanding please refer to their documentation for more info.
95+
96+
## 📁 File structure and package management 📦 <a name="package-management"></a>
97+
98+
This starter monorepo has three types of workspaces:
99+
100+
- `/apps/*` for all expo & next.js versions of your apps (consumes `'features'` 👇)
101+
- `/features/*` features of your app, grouped together by feature name (consumes `'packages'` 👇)
102+
- `/packages/*` for all shared dependencies / library code used in multiple apps or features
103+
104+
```
105+
├── apps/
106+
│ └── expo/ 👉 Where all Expo & mobile specific config for {app-name} lives
107+
│ └── app.json ➡️ Expo app config (e.g. App name, icon, landscape / tablet support)
108+
│ └── app/ ➡️ File-based Routing & Navigation Setup for mobile (using 'app-core/screens/')
109+
│ └── (generated)/ ➡️ File based routing generated from `routes/` in features or packages
110+
│ └── _layout.tsx ➡️ Root layout for all app screens (e.g. tab bar, drawer, etc.)
111+
│ └── index.tsx ➡️ Home & starting screen for the app
112+
│ └── babel.config.js ➡️ Babel transpilation config for Expo
113+
│ └── index.js ➡️ Mobile entrypoint loader for App.tsx
114+
│ └── metro.config.js ➡️ Metro bundler config for react-native
115+
│ └── package.json ➡️ yarn-workspace config, lists core expo & react-native dependencies
116+
│ └── tsconfig.json ➡️ Typescript config for Expo
117+
│ └── webpack.config.js ➡️ Enables PWA browser testing with Expo (no SSR)
118+
│
119+
│ └── next/ 👉 Where all Next.js, Server & API config for {app-name} lives
120+
│ └── public/ ➡️ favicon, app icons & other static assets (e.g. images & fonts)
121+
│ └── app/ ➡️ File-based Routing & Navigation Setup for Web (using 'app-core/screens/')
122+
│ └── (generated)/ ➡️ File based routing generated from `routes/` in features or packages
123+
│ └── head.tsx ➡️ HTML wrapper for head & meta tags (+ SSR styles)
124+
│ └── layout.tsx ➡️ Root layout for all web pages (e.g. headers / footers / nav)
125+
│ └── page.tsx ➡️ Web Homepage (e.g. using 'app-core/screens/HomeScreen.tsx')
126+
│ └── src/
127+
│ └── pages/ ➡️ directory based routes (using 'app-core/screens/')
128+
│ └── api/ ➡️ directory based api routes (using 'app-core/resolvers/')
129+
│ └── graphql.ts ➡️ GraphQL client from 'app-core/graphql/'
130+
│ └── babel.config.js ➡️ Babel transpilation config for Next.js
131+
│ └── next.config.js ➡️ Next.js config, modules to transpile & plugins to support
132+
│ └── package.json ➡️ yarn-workspaces config, lists core next.js dependencies
133+
│ └── tsconfig.json ➡️ Typescript config for Next.js
134+
|
135+
|── features/
136+
│ └── app-core/ 👉 Where all core cross-platform code for {app-name} lives
137+
│ └── components/ ➡️ Molecules / Atoms / Common UI used in 'screens/'
138+
│ └── graphql/ ➡️ Shared code for the GraphQL API client (optional)
139+
│ └── resolvers/ ➡️ Shared resolvers used in both in API routes or GraphQL API
140+
│ └── screens/ ➡️ Page templates used in App.tsx and next.js's 'pages/' directory
141+
│ └── routes/ ➡️ Write-once routing for both web & mobile (see 'app/(generated)/' in expo & next)
142+
│ └── package.json ➡️ config required by yarn-workspaces, lists dependencies that don't fit anywhere else
143+
│ └── {app-feature}/ 👉 Code shared across apps, ideally same structure as 'features/app-core'
144+
│ └── package.json ➡️ config required by yarn-workspaces, list dependencies specific to this feature
145+
│
146+
├── packages/
147+
│ └── @aetherspace/ ➡️ Primitives, utils & helpers for working with the GREEN stack
148+
│ └── schemas/ ➡️ A set of Zod powered schema utils for building single sources of truth
149+
│ └── @config/ ➡️ list of ts & other configs to use / extend from in next or expo apps
150+
│ └── {comp-lib}/ 👉 Code shared across apps, ideally same structure as 'features/app-core'
151+
│ └── package.json ➡️ yarn-workspace config, list dependencies specific to this package
152+
│
153+
├── node_modules/ ➡️ Contains all modules for the entire monorepo
154+
├── package.json ➡️ Root yarn-workspaces configuration + helper scripts, core developer only dependencies
155+
└── turbo.json ➡️ Monorepo config, manages dependencies in build scripts + caching of tasks
156+
```
157+
158+
```
159+
💡 `{app-feature}`, `{app-name}` & `{comp-lib}` are just placeholders and you **can** have multiple of these
160+
```
161+
162+
#### 📦 Keep your apps seperate with `/apps/*` & `/features/*` workspaces:
163+
164+
For every app you're building in this monorepo, you'll need a few folders:
165+
166+
- `/apps/next` - Entry for web where only next.js related config/setup for an app should live.
167+
Should list only core next.js related deps & polyfills.
168+
- `/apps/expo` - Entry for mobile where only expo related config/setup for an app should live.
169+
Should list only core react-native and expo related deps.
170+
- `/features/{app}-core` - Where most of your core app specific UI, logic and screens will live.
171+
Should list app dependencies not listed elsewhere.
172+
173+
In each of these folders own a `package.json` file, where a `name` property should be specified to identify that workspace. This name can then be referenced during installs via e.g.
174+
175+
```shell-script
176+
yarn workspace next add {package-name}
177+
```
178+
179+
#### To install Expo modules for the specific Expo SDK you're using:
180+
181+
```shell-script
182+
yarn expo-cli install {package-name}
183+
````
184+
Which will run `yarn workspace expo-app expo-cli install {package-name}` under the hood.
185+
186+
## 👾 Stack and Template benefits + Next steps 👾 <a name="benefits-next-steps"></a>
187+
188+
If you've read the sections above, It's likely the **ease** of use, **time saving** capabilities and **scalability** of this stack & template are clear.
189+
190+
The starter repo comes with some opinionated extra packages and abilities.
191+
Here's a list of what you can start doing out of the box:
192+
193+
- Link pages and screens cross platform with the `<Link>` component from `aetherspace/navigation`
194+
- Use tailwind to style UI responsively on web / mobile with `<AetherView tw="sm:px-2">` / `tailwind-rn`
195+
- Add illustrations or icons with `react-native-svg`
196+
- Bring the power of GraphQL to JSON or REST apis with `aetherResolver()` and schemas as single sources of truth.
197+
- Document your components and APIs with Storybook.
198+
- Deploy to vercel with `yarn deploy` or `vercel --prod --no-clipboard` ([view live](https://aetherspace-green-stack-starter.vercel.app/))
199+
- Deploy to netlify [via this guide](https://www.netlify.com/blog/2020/11/30/how-to-deploy-next.js-sites-to-netlify/) ([view live](https://aetherspace-green-stack-starter.netlify.app/))
200+
201+
Possible next steps:
202+
- Animate UI elements with `react-native-reanimated` or `moti`
203+
- Add auth with [AuthSession](https://docs.expo.dev/versions/latest/sdk/auth-session/) ([Expo Examples](https://docs.expo.dev/guides/authentication/))
204+
205+
## 💼 Why this makes sense from a user, dev & business perspective <a name="why-this-makes-sense-from-a-business-perspective"></a>
206+
207+
**For users:**
208+
- Solutions built for how they prefer to use software, whether that's on a phone, tablet or desktop.
209+
- Can share any page or feature with a link, which will open in the correct app or browser.
210+
- Full feature parity across all platforms.
211+
212+
**For developers:**
213+
- Write-once UI, logic, routing, data fetching & resolvers
214+
- Easily onboard new devs to the project with auto-generated Storybook docs
215+
- Save time & reduce risk by defining data structure once, instead of 4 times for types, graphql, docs & validation
216+
217+
**For businesses:**
218+
- Speed and flexibility to build/update features and pages for any platform.
219+
- Reach more users by being available on more devices.
220+
- Free organic leads from web SEO, which you can easily guide to mobile where higher conversions happen.
221+
222+
> Whether you're a startup or established company, having both web and mobile apps is a great competitive advantage. There are many stories of market leaders suddenly being overtaken because the competition were able to move faster or had more devices their solution was available on for their customers.
223+
224+
This stack makes it near effortless to enable extra platforms. It helps keep teams small and enables them to move fast when building new pages or features for phones, tablets and/or the web.
225+
226+
**More deliverables for less time invested in turn means flexibility in one or more of these areas:**
227+
228+
- ... negotiation room about budget or deadlines (in case of client work)
229+
- ... 💰 to be distributed among the entire team
230+
- ... 🕗 available for experimentation
231+
- ... budget available to market the product
232+
233+
<details>
234+
<summary>Show full 🕗🕗 to 💰💰💰 Comparison</summary>
235+
236+
---
237+
238+
Let's talk Return on Investment:
239+
240+
> 🕗 = time required = devs / teams / resources invested
241+
> 💰 = deliverable sale value = costs to build + profit margin
242+
> ROI = 🕗 -> _sold for_ -> 💰
243+
244+
Web only project ROI = 🕗🕗 -> 💰💰
245+
246+
- 🕗 Web Front-End 💰
247+
- 🕗 General Back-End (REST / GraphQL + Templates / SSR) 💰
248+
249+
Native iOS + Android project ROI = 🕗🕗🕗 -> 💰💰💰
250+
251+
- 🕗 iOS App with Swift 💰
252+
- 🕗 Android app with Java 💰
253+
- 🕗 API Back-End (REST / GraphQL) 💰
254+
255+
React-Native Mobile App ROI = 🕗🕗 -> 💰💰 to 💰💰💰
256+
257+
- 🕗 iOS + Android App with RN 💰(💰)
258+
- 🕗 API Back-End (REST / GraphQL) 💰
259+
260+
Expo Mobile + PWA ROI = 🕗🕗 ->💰💰 to 💰💰💰💰
261+
262+
- 🕗 iOS + Android + PWA with Expo & RN (Web without SSR) 💰(💰💰)
263+
- 🕗 API Back-End (REST / GraphQL) 💰
264+
265+
> Now, things get _really_ interesting when you try to compare full cross-platform apps
266+
267+
Full Cross Platform with Separate Dev Teams ROI = 🕗🕗🕗🕗🕗🕗🕗 -> 💰💰💰💰💰💰💰
268+
269+
- 🕗 Web Front-End 💰
270+
- 🕗 iOS App with Swift 💰
271+
- 🕗 Android app with Java 💰
272+
- 🕗 Windows App Dev Team 💰
273+
- 🕗 MacOS App Dev Team 💰
274+
- 🕗 Linux App Dev Team 💰
275+
- 🕗 API Back-End (REST / GraphQL) 💰
276+
277+
Full Cross Platform with GREEN stack ROI = 🕗🕗 -> 💰💰 to 💰💰💰💰💰💰💰
278+
279+
- 🕗 Web (PWA & SSR & Web Vitals) + iOS + Android + Windows + MacOS + Linux 💰(💰💰💰💰💰)
280+
- 🕗 Back-End (REST + GraphQL + SSR + Static Exports + ISSG + universal JS utils thanks to Next.js) 💰
281+
282+
**Key takeaway: Always build or upsell more platforms / devices the app could run on**
283+
284+
</details>
285+
286+
## When not to use the GREEN stack? 🤷‍♂️ <a name="when-not-to-use-green-stack"></a>
287+
288+
The GREEN stack is unlikely to be the best fit when your project...
289+
290+
- ... will always be web only 👉 Use `next.js`
291+
- ... will always be mobile only 👉 Use `Expo`
292+
- ... will always be desktop only 👉 Use `Electron` + `React` / `Vue` / `Svelte`
293+
- ... is very Bluetooth / AR / VR / XR heavy 👉 Go native with `Swift` / `Java`
294+
- ... is not using React 👉 Use `Svelte` / `Vue` + `Ionic`
295+
- ... has no real need for Server Rendering, SEO or Web-Vitals 👉 Use `Expo` (+ Web Support)
296+
- ... is using React, but the project is too far along and has no budget, time or people to refactor 🤷‍♂️
297+
298+
If your project has required dependencies / SDKs / libraries that are either not available in JS, are not extractable to API calls or cannot function cross-platform, this may also not be a good solution for your use-case\*.
299+
300+
```
301+
🛠 * However, for JS libs, you could always try adding cross platform support yourself with `patch-package`
302+
```
303+
304+
## 📚 Further reading / Relevant docs: <a name="relevant-docs"></a>
305+
306+
- [Expo](https://docs.expo.dev/), [React Native](https://reactnative.dev/docs/getting-started), [Expo-Router docs](https://expo.github.io/router/docs/)
307+
- [Yarn Workspaces](https://classic.yarnpkg.com/lang/en/docs/workspaces/), [Turborepo docs](https://turborepo.org/docs)
308+
- [Next.js](https://nextjs.org/docs/getting-started), [app-directory](https://beta.nextjs.org/docs/getting-started), [React-Native-Web docs](https://necolas.github.io/react-native-web/docs/)
309+
- [Apollo Server docs](https://www.apollographql.com/docs/apollo-server/)
310+
311+
## Frequently Asked Questions 🤔
312+
313+
#### How does automatic docgen work?
314+
315+
See the README on [Automation](/packages/@registries/README.md) or the [Anouncement post](https://dev.to/codinsonn/how-to-compete-with-elons-twitter-a-dev-perspective-4j64)
316+
317+
#### I have a question about the license.
318+
319+
Check out the [License](/LICENSE.md) and its FAQ section.
320+
321+
---
322+
323+
<p>
324+
<a aria-label="sponsor @codinsonn on Github for full access" href="https://github.com/sponsors/codinsonn">
325+
<img src="https://img.shields.io/static/v1?label=Sponsor&style=for-the-badge&message=%E2%9D%A4&logo=GitHub&color=%23fe8e86" target="_blank" />
326+
</a>
327+
<a aria-label="the aetherspace green stack starter is free to use for some, but paid for professional use." href="/LICENSE.md" target="_blank">
328+
<img align="right" alt="License: MIT" src="https://img.shields.io/badge/Licence-Custom-green?style=for-the-badge" target="_blank" />
329+
</a>
330+
</p>
331+
332+
</details>
333+
334+
---
335+
336+
Thorr / [@codinsonn.dev](https://codinsonn.dev)'s personal website & app.
337+
338+
Built with [the GREEN stack](https://github.com/sponsors/codinsonn), [Aetherspace](https://github.com/sponsors/codinsonn), [Expo-Router](https://expo.github.io/router/docs) & the [Next.js App Dir](https://beta.nextjs.org/docs/app-directory-roadmap)

0 commit comments

Comments
 (0)