Formation.tools App

⚠️ Yups, this is GPL3 because I’m using @rasendubi’s uniorg. I’ve been freaking out a bit about the licensing point for a while but then again… if I’m honest about this being a scrappy prototype, I should be fine sharing the code. 🤷🏿‍♂️ If there is a moat to this idea that I’m flirting with, it will not be around this part. There are a lot of things around offering this as a managed service, covering the collaborative editing bits and also adding integrations and assist features like GPT-3-powered “ELI5 style” paraphrasing features to ensure that different audiences can consume the same content in a manner that serves them well enough. Imagine paraphrasing a complex technical text to extract the 3 core points for a legal or business audience – not saying that this is even remotely possible but it’s part of the marketplace and platform idea that I’m also playing with. Too early to say though. I’m collecting brutally honest feedback to figure out if I’m just full of it or if I maybe unto something so don’t be shy and hit me up if this speaks to you.

Usage

Enter the link to a raw dump of any Org file on the internet into the text field in the navigation bar. Here are some pages to visit:

1. https://gitlab.com/pages/org-mode/-/raw/master/post0.org
2. https://raw.githubusercontent.com/formation-tools/product/main/README.org

Development

1. Run npm ci to install dependencies.
2. Run npm run dev for UI development (and find the port to which to navigate your browser in the console output)
3. Run npm run fmt:fix before committing to ensure that your changes are are compatible with the styleguide.

Install dependencies

💡 We only want to use npm install when we are installing new packages and have the express intention of making changes to the package-lock.json file.

Using npm ci as opposed to npm install will ensure that we do not casually update the package-lock.json file (in case one is using an older version of npm that specificied in the package.json engines property). Casual changes to the package-lock.json file can complicate merging since the package-lock.json file can get quite noisy, resulting to many changes that one needs to painstakingly isolate in a merge conflict.

Start development session

When working on the UI, running npm run dev is helpful. When working on logic it may actually be more helpful to watch core logic source files and run npm run build as this recompiles the code on every change and communicates compiler errors more clearly.

ls core/**/*.ts core/**/*.tsx pages/**/*.tsx components/**/*.tsx  | entr  npm run build

💡 While working on the parsing or rendering logic, the npm run build tool may be the tool to use.

Format code (according to project styleguide)

This is important because some editors fudge the source files a bit which produces a lot of changes that don’t really affect the UI or the logic at all and are therefore just noise. Running everything through the same formatter will ensure that the only thing ending up in the commit are changes to UI or logic and not just editor opinions. 😅

💡 Run npm run fmt:fix:watch in a separate terminal to not have to think about this. It will watch relevant source files and rerun the formatter whenever they change and offering us less thing to think about while developing.

Test code

Run npm run test in order to run the tests. The test runner is pretty convenient and will provide facilities to do the following from within the test running TUI:

• narrow down tests based on patterns
• generate or update snapshots when changes are detected
• retrigger complete test re-runs

Resources

Product respository: it contains all relevant information and the ROADMAP.org file.

• App respository GitLab
• Figma file
• Issues Board
• Vercel app
• Vercel dashboard

Technologies

• Next.js
• Typescript
• SWR
• react-syntax-highlighter, used for the Code component
• Storybook: You can check our Storybook here

Analytics

We are using Plausible for analytics and load the necessary script using the afterInteractive strategy to improve the load performance.

Supabase

Tooling

You can install the Supabase CLI from npm using the following command:

npm install --save-dev supabase

You can use the cli through the npx supabase command.

Note that the npm-install binary not reliably work in NixOS because it attempts to resolve libs to FHS paths which are not resolvable on some Nix systems. There is a commit that packages supabase for Nix that we’ve pulled into our nix shell config to install nix on NixOS. So a nix shell should bundle supabase through the supabase command.

Base Configuration

We need to configure the following env variables for Supabase to work:

• NEXT_PUBLIC_SUPABASE_URL
• NEXT_PUBLIC_SUPABASE_ANON_KEY

Observe the following snippet which you can adapt and add to our file:.env.local to get Supabase set up.

NEXT_PUBLIC_SUPABASE_URL=https://blah.tld
NEXT_PUBLIC_SUPABASE_ANON_KEY="blah"

Auth

Configure Supabase Auth by:

1. configuring a GitHub OAuth app and a GitLab OAuth app
2. defining NEXT_PUBLIC_VERCEL_URL in your file:.env.local to http://localhost:3000 for local development or the actual app URL otherwise (which is automatically set in Vercel[fn:1]

   NEXT_PUBLIC_VERCEL_URL=http://localhost:3000
       

Footnotes

[fn:1] In case you deploy your app to Vercel, the NEXT_PUBLIC_VERCEL_URL is automatically set to the deployment URL, also for preview deployments.