This post starts with a brief introduction. If you want to jump down to the tutorial, click [here](/blog/supabase-next-analytics#how). You can also see the live updating views in action in the top right of this page! The analytics events themselves require no JavaScript and occur completely on the server thanks to the [new (in beta) Next.js middleware](https://nextjs.org/docs/advanced-features/middleware). If you have JavaScript enabled, the view count should live update thanks to Supabase Realtime. You can try it by opening the page in a new tab and eyeing the view count.

**Contents**
- [Motivations](/blog/supabase-next-analytics#motivations)
- [How to do it](/blog/supabase-next-analytics#how)
    - [Supabase: Setting up the Database and Realtime](/blog/supabase-next-analytics#supabase-setting-up-the-database-and-realtime)
    - [Next.js: Adding server-side analytics](/blog/supabase-next-analytics#nextjs-adding-server-side-analytics)
    - [Next.js: Adding a live updating view counter](/blog/supabase-next-analytics#nextjs-adding-a-live-updating-view-counter)
- [Next steps](/blog/supabase-next-analytics#next-steps)

## Motivations
When possible, I avoid requiring JavaScript and exposing my users to unnecessary tracking. The problem is that I decided I wanted to track views on my blog, and [Next.js analytics](https://nextjs.org/analytics) don't provide the vanity metrics I'm looking for. I previously used [Matomo](https://matomo.org/) analyzing my nginx log, and while matomo is a fantastic piece of open-source software, I don't want to mess with the PHP API (or use PHP for the first time in ~7 years) in order to get post views on the front-end.

Coincidentally, Supabase [announced their Series B](https://techcrunch.com/2022/05/10/supabase-raises-80m-series-b-for-its-open-source-firebase-alternative/) a few days ago, and that pushed me to finally give it a try and see how their product works. If you're unfamiliar with Supabase, they're an open-source Firebase alternative with a hosted option: you get a postgres database and fancy dashboard and CLI for creating tables, edge functions, authentication and more. They also make it incredibly easy to subscribe to database updates, making syncing and connectivity a breeze. 

So far, I love everything about it except the dashboard: everything is *so slow*. Creating a new, unnamed SQL query can take 5 seconds:

<video controls="true">
    <source src="/blog/supabase/slow.webm" type="video/webm">
    <source src="/blog/supabase/slow.mp4" type="video/mp4">
</video>

Dashboard slowness aside, this tutorial will walk you through using Supabase and Next.js middleware to have live-updating view counts and server-side analytics.

## How

Note that this tutorial expects you to already have a Next.js project. If you don't, I recommend following the official [Next.js tutorial](https://nextjs.org/learn/basics/create-nextjs-app).

### Supabase: Setting up the Database and Realtime
1. Register an account with Supabase here: https://app.supabase.io/
2. Create a Supabase project and fill out the new project form. 

    ![A screenshot of the Supabase page with the New Project button clicked](/blog/supabase/signup.png)
    > If the above step confuses you, you need to click your organization in the dropdown of the 'new project' button. That took me a little too long to figure out...

    ![A screenshot of the Supabase new project page](/blog/supabase/create-project.png)

3. Navigate to the `Table Editor` in the left nav bar and click new table. Fill it out to match below, and be sure to click the gear icon to deselect allowing null:
    ![A screenshot of the new table field showing 4 columns: an int8 ID, a text slug, an int8 views with a default value of 1, and an updated_at date column with a default value of "now()".](/blog/supabase/create-table.png)
    Alternatively, if you're comfortable with SQL, you can write and save a SQL query that you can use again in the future. It may look something like this:
    ```sql
    CREATE TABLE analytics (
        id bigint GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
        slug text UNIQUE NOT NULL,
        views bigint DEFAULT 1 NOT NULL,
        updated_at timestamp DEFAULT NOW() NOT NULL
    );
    ```

    You can input the query in the `SQL Editor` tab in the left nav bar a few options below the `Table Editor`.

4. Now, we need to add a stored procedure (AKA a stored SQL function we can call from the Supabase API). Navigate to the `Database` tab in the left nav bar and select the `Functions` menu item inside:

    <img alt="A screenshot showing the functions menu item location in the sidebar" src="/blog/supabase/sidebar-functions.png" height="450px" style="margin: var(--gap)" />

    > Note that Supabase offers Database Functions and Edge Functions &mdash; we're using Database Functions!


5. Click `Create a new Function` in the top right and and fill the settings out to match below. We're establishing a name we can use to reference the function, the schema (AKA what tables it has access to), the return value (`void` in this case), and a single argument that is the page path.
    ![A screenshot of the function creation view](/blog/supabase/create-function.png)

    The query is as follows:
    ```sql
    BEGIN
        IF EXISTS (SELECT FROM analytics WHERE slug=page_slug) THEN
            UPDATE analytics
            SET views = views + 1,
                updated_at = now()
            WHERE slug = page_slug;
        ELSE
            INSERT into analytics(slug) VALUES (page_slug);
        END IF;
    END;
    ```

    The function updates the row if it exists (if the `page_slug` argument is in the `slug` column), otherwise it creates a new row. 
    
    P.S. I believe I found this query somewhere online but now I can't find the original source &mdash; if you recognize it please let me know so I can provide credit!

6. Now we need to enable [Realtime](https://github.com/supabase/realtime) so Supabase broadcasts our changes when we subscribe. Navigate to the `Database` item in the navigation bar and select `Replication` in the side menu. You should see the following page:
    ![A screenshot of the empty replication page, showing prepopulated a `supabase_realtime` row](/blog/supabase/replication.png)

7. Click the `0 tables` button the `Source` column and toggle the new table you created (I called mine `analytics`):
    ![The analytics table has been enabled in the replication page](/blog/supabase/enable-replication.png)

8. Finally, navigate to the `Settings` at the bottom of the navigation and select the `API` submenu. Copy down the `anon public` API key, the `service_role` API key, and the project URL in the `Configuration` box: we'll need them in the next section.

> **Do not** ever expose or share your `service_role` key &mdash; it bypasses row-level security and should only ever be used and seen by your server or you. 


### Next.js: Adding server-side analytics

1. First, we need to add the API keys and project URL to our environment, which will let us access them in our code. If you're hosting with [Vercel](https://vercel.com), I recommend using their CLI or dashboard to add the keys, which you can read about [here](https://vercel.com/docs/concepts/projects/environment-variables). Otherwise, create or modify your `.env` file to contain the following:

    ```bash title=.env
    NEXT_PUBLIC_SUPABASE_URL=<your URL>
    NEXT_PUBLIC_SUPABASE_ANON_KEY=<anon_public_key>
    SUPABASE_SERVICE_KEY=<service_role_key>
    ```

    If you're just creating the .env, be sure to add it to your `.gitignore` so it won't be pushed online.

    > For security, Next.js doesn't automatically expose your environment variables to the client. If you want to do that, you need to prefix the key with `NEXT_PUBLIC_`. This is a great feature, but don't let it stop you from manually verifying you aren't exposing your service key elsewhere. 

2. Add the `@supabase/supabase-js` package from npm to your project:
    ```bash
    yarn add @supabase/supabase-js
    ```
    or
    ```bash
    npm install @supabase/supabase-js
    ```

3. Create two files, `supabase/public.js` and `supabase/private.js`, where you want to; I put them in `lib`. `Private` will contain a connection with the `service_role` key while `public` will use the anon one. Two files aren't necessary, but I like distinguishing them so I can be sure which I'm using.

    They should each look something like this:

    ```javascript collapsible title=public.js
    import { createClient } from '@supabase/supabase-js'

    if (!process.env.NEXT_PUBLIC_SUPABASE_URL || !process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY) {
        throw new Error('Missing env vars SUPABASE_URL or SUPABASE_ANON_KEY')
    }

    const publicClient = createClient(
        process.env.NEXT_PUBLIC_SUPABASE_URL,
        process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY
    )

    export default publicClient
    ```

    ```js collapsible title=private.js
    import { createClient } from '@supabase/supabase-js'

    if (!process.env.SUPABASE_URL || !process.env.SUPABASE_SERVICE_ROLE_KEY) {
        throw new Error('Missing env vars SUPABASE_URL or SUPABASE_SERVICE_ROLE_KEY')
    }

    const privateClient = createClient(
        process.env.SUPABASE_URL,
        process.env.SUPABASE_SERVICE_ROLE_KEY
    )

    export default privateClient
    ```


    The only difference between `private` and `public` is the second argument passed to `createClient`: change that depending on which you want to use.

4. Create an [API route](https://nextjs.org/docs/api-routes/introduction) for submitting views. You could do this directly from the middleware but adding it as a serverless function gives you more freedom to extend it in the future. Also note that anyone can trigger this function, so you may want to protect it by adding a new environment variable and sending that with the request from the middleware. Then, only your server requests will ever have that value and can be verified as legitimate.

    ```typescript title=pages/api/view.ts
    import { NextApiRequest, NextApiResponse } from "next";
    import supabase from '@lib/supabase/private'

    const handler = async (req: NextApiRequest, res: NextApiResponse) => {
        if (req.method === 'POST') {
            // `increment_views` is the name we assigned to the function in Supabase, and page_slug is the argument we defined.
            await supabase.rpc('increment_views', { page_slug: req.body.slug });
            return res.status(200).send('Success');
        } else {
            return res.status(400).send('Invalid request method');
        }
    }

    export default handler
    ```

    > The above code is in TypeScript; if you want JavaScript, you can remove the first `import` and change the function definition to `const handler = async (req, res) =>`. I included this to try and encourage you to try TypeScript if you aren't already; it's very helpful for exploring unfamiliar APIs, like the Next.js requests and responses.

5. Create a `pages/_middleware.{jsx,tsx}` file. The middleware will run on the server before every page request; nothing inside it is ever exposed to the client so we can safely use our private Supabase lib. However, we'll actually just send a POST request to our API handler instead. 

    ```typescript pages/_middleware.tsx
    import { NextMiddleware, NextResponse,  } from 'next/server'
    const PUBLIC_FILE = /\.(.*)$/

    export const middleware: NextMiddleware = async (req, event) => {
        const pathname = req.nextUrl.pathname
        // we ignore running this middleware when the request is to a serverless function or a file in public/. 
        // This is purely optional.
        const isPageRequest =
            !PUBLIC_FILE.test(pathname) &&
            !pathname.startsWith("/api")

        const sendAnalytics = async () => {
            const slug = pathname.slice(pathname.indexOf("/")) || "/"

            // Change your production URL!
            const URL = process.env.NODE_ENV === 'production' ? 'https://maxleiter.com/api/view' : 'http://localhost:3000/api/view'
            const res = await fetch(`${URL}`, {
                method: 'POST',
                headers: {
                    'Content-Type': 'application/json',
                },
                body: JSON.stringify({
                    slug,
                }),
            })

            if (res.status !== 200) {
                console.error('Failed to send analytics', res)
            }
        }

        // event.waitUntil is the real magic here: 
        // it won't wait for sendAnalytics() to finish before continuing the response,
        // so we avoid delaying the user.
        if (isPageRequest) event.waitUntil(sendAnalytics())
        return NextResponse.next()
    }
    ```

6. You should now verify your views table is updating by loading pages and viewing the Supabase dashboard. If it's not updating, verify your connection details and try exploring the Supabase logs.


### Next.js: Adding a live-updating view counter

1. Now we can finally add our updating view count. In your React component, import your *public* Supabase client.
    ```javascript title=components/something.js
    import supabase from '@lib/supabase/public'
    ```
2. Make views a member of your state:
    ```javascript title=components/something.js highlight=4,5,6
    import supabase from '@lib/supabase/public'

    const Component = () => {
        // You may want to pass in an initial value for views if you're using getStaticPaths or similar.
        // That way, it won't start at 0 when the client loads.
        const [views, setViews] = useState(0)
        return (...)
    }
    ```
3. Add a `useEffect` hook to subscribe and unsubscribe to changes on mount or unmount respectfully. This is *all it takes* to subscribe to recieve the changes made to the `analytics` table.

    ```javascript title=component/something.js highlight=8-27,29
    import supabase from '@lib/supabase/public'

    const Component = () => {
        // You may want to pass in an initial value for views if you're using getStaticPaths or similar.
        // That way, it won't start at 0 when the client loads.
        const [views, setViews] = useState(0)

        // Subscribe to view updates.
        // Note that `id` is something I store manually on page creation so I can associate 
        // each page with itself from the DB. 
        // In practice, I recommend looking into subscribing to low level changes:
        // https://supabase.com/docs/reference/javascript/subscribe#listening-to-row-level-changes
        useEffect(() => {
            const sub = supabase
                .from('analytics')
                .on('UPDATE', (payload) => {
                    if (payload.new.id === id) {
                        setViews(payload.new.views)
                    }
                })
                .subscribe()

            // The return function of a useEffect is fired on unmount
            return () => {
                sub.unsubscribe()
            }
        }, [id])

        return (<div>{views} {views.length === 1 ? 'view' : 'views'}</div>)
    }
    ```

4. And there you have it! Automatically updating analytics that don't require JavaScript to be recorded! You can verify it works by opening the page in a new tab.

### Next steps

There's quite a lot you can do from here, but here are some recommendations:
1. Only allow unique visitors, perhaps by storing IP hashes or using localStorage. This could probably be accomplished with Supabase Edge functions? 
2. Build a visualization page for interacting and querying the results
3. Expand your analytics to include things like keeping track of the `referer` value. 
4. Ignore certain user agents to reflect a more accurate view count 

A step-by-step guide to page views and server analytics

Live updating page views with Supabase and Next.js


I was watching Reactathon 2022 this weekend and enjoyed the Syntax fm live session. They did a great audience interaction bit with quizzing them about what a particular piece of CSS did. Inspired, I decided to build a quick quiz.

I decided to take a look into Supabase (coincidentally, they just raised a modest $80M series B). I'm happy I did, because the ease of setting up the database and realtime support was incredible. With a few hours of work I've created a live-updating quiz where you can see others results (after you've voted yourself). You can try the quiz at [/ie-or-css3](/ie-or-css3). I also recommend listening to the Syntax fm segment, timestamped [here](https://youtu.be/Ck-e3hd3pKw?t=22032).


A quick quiz I created to explore Supabase

Internet Explorer or CSS3?

Below is a short list I wrote up for people who are comfortable building websites (with any technology) but want to improve their work, whether that be in terms of loading speeds, software quality, or accessibility.


TL;DR:
- [Use WAVE](/blog/easy-site-improvements#wave)
- [Compress your images](/blog/easy-site-improvements#compress-your-images)
- [Embrace semantic HTML](/blog/easy-site-improvements#embrace-semantic-html)
- [Don’t use JavaScript to replace browser controls](/blog/easy-site-improvements#dont-use-javascript-to-replace-browser-controls)
- [Invest in learning your developer tools](/blog/easy-site-improvements#invest-in-learning-your-developer-tools)

## WAVE 

[WAVE](https://wave.webaim.org/) is a suite of tools for finding, diagnosing, and fixing accessibility problems. It's my first step for finding the lowest hanging improvements. It helps you not just fix your errors but understand them by guiding you through the relevant part of the HTML5 spec in plain language. Below you can see a screenshot of the tool being applied to https://webaim.org. 
![Screenshot of the WAVE tool being used on webaim.org](/blog/site-improvements/webaim.png)

## Compress your images
Loading times are important. Someone more business savvy than me would say something about bounce rates and loading times being correlated, but I won't do that. There are a lot of tools for automating this, like [WebP Express](https://wordpress.org/plugins/webp-express/) for WordPress, but no complicated infrastructure is necessary. For things similar to this blog I manually compress the images locally using [ImageOptim](https://imageoptim.com/mac), an open-source Mac app. Be sure to use the right tool for the job though; for example, I use [svgo](https://github.com/svg/svgo) for optimizing SVGs. I also haven't found a better PNG optimizer than the online https://tinypng.com/, so if you have a replacement that works locally please let me know!

## Embrace semantic HTML
This has been [covered](https://webflow.com/blog/html5-semantic-elements-and-webflow-the-essential-guide) [pretty](https://www.semrush.com/blog/semantic-html5-guide/) [extensively](https://www.freecodecamp.org/news/semantic-html5-elements/) so I’ll keep it short, but use tags like `header`, `footer`, `nav`, and `main`. MDN has a great list of all the valid elements here: https://developer.mozilla.org/en-US/docs/Web/HTML/Element. Using semantic HTML means you can avoid manually assigning `role` tags while keeping your HTML legible for yourself and the page usable for users of assistive technologies. Be sure to also familiarize yourself with and use the [relevant ARIA labels](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) when a semantic element isn't possible or if they would improve the user experience. 

## Don’t use JavaScript to replace browser controls
Unlike a lot of other advice that will say don’t do this because users might have JavaScript disabled, I think the more important reason to do this is you can’t do it better than the browser (after all, 99.4% of users have JavaScript enabled[^1]). I don’t say this because the browser developers are “better” than you, but because the user is used to the browser’s controls. The first item of this list should really be “don’t subvert the users' expectations.” *Don’t subvert the users' expectations.* Handling the nuances of keyboard and event handling, form submissions, and similar are difficult enough. 

## Invest in learning your developer tools
I don’t mean how to view the console and read `console.log`s. I mean investing in learning how to use the debugger, read the network tab, inspect (and understand) [memory snapshots](https://www.bitdegree.org/learn/chrome-memory-tab), and monitor your bundle size to be sure you’re not including unnecessary dependencies. If you’re using Next.js, I recommend setting up the [@next/bundle-analyzer](https://www.npmjs.com/package/@next/bundle-analyzer) package. If you’re using react, redux or vue, check out their browser extensions for useful debugging tools and component inspection. 

[^1]:. According to https://webaim.org/projects/screenreadersurvey9/#javascript, which absolutely has some selection bias. [⏎](/blog/easy-site-improvements#ref:1)


A list of simple tips for developing a more accessible and user-friendly web.

Easy ways to improve your websites accessibility and performance


<small>\* hackers: users of hacker news</small>

Yesterday, when I probably should have been doing something productive, I instead [asked hacker news users for links to their personal sites](https://news.ycombinator.com/item?id=30934529).

It got far more replies than I expected (over 1000 at the time of writing) so I had the idea to do some scraping and see how commenters build and host their sites.

I wrote a quick-and-dirty typescript script (at the bottom of page) for scraping, pinging, and sorting the comments. I could've used a pre-existing library or service for determining tech used on the sites, but where's the fun in that? I’d have loved to add features like checking for git repository links and doing some API calls for a more in-depth analysis, but I’ll leave the complicated parts as exercises for the reader.

If I were to do this all again, I would absolutely not choose JavaScript. Just 0 real benefits; I spent more time than I care to admit bashing my head before remembering `Promise.allSettled` exists. I should've just used Python.

## The stats:

Of the 721 top level comments, 692 contained links and were analyzed at the time of writing. I only looked at the first link in a comment, timed out after 30 seconds, and skipped invalid/self-signed certificates. Also not that none of the categories are exclusive &mdash; sites can count towards multiple stats.

#### Some fun ones:

- 4 sites offer the `onion-location` response header
- One `"x-nananana": "Batcache",` response header
- One site is behind `Apache/2.4.7`, which was released in 2013 and has [multiple CVEs](https://www.cvedetails.com/vulnerability-list/vendor_id-45/product_id-66/version_id-524064/Apache-Http-Server-2.4.7.html)
  - This is also the only site to advertise `mod_perl`, so do with that what you may.

#### The scraped stuff:

- Contains JavaScript: 567 (81%)
- Github Pages: 146 (21%)
- Cloudflare: 141 (20%)
- Nginx: 114 (16%)
- Netlify: 83 (11%)
- Apache: 70 (10%)
- Vercel: 50 (7%)
- Bootstrap: 45 (6.5%)
- Gatsby: 30 (4.3%)
- Nextjs: 28 (4%)
- Amazon S3: 27 (3.9%)
- Wordpress: 22 (3.2%)
- Cloudfront: 17 (2.5%)
- Express: 16 (2.3%)
- PHP: 14 (2%)
- Caddy: 9 (1.3%)
- Litespeed: 8 (1.5%)
- Open Resty: 8 (1.5%)
- Google App Engine: 3 (0.43%)
- FlyIO: 3 (0.43%)
- MicorosftIIS: 3 (0.43%)
- Drupal: 2 (0.29%)
- Tailwind: 2 (0.29%)
- Lighttpd: 2 (0.29%)
- Godlighty: 1 (0.14%)
- Perl: 1 (0.14%)
- Neocities: 1 (0.14%)
- Asp.NET: 1 (0.14%)
- Gatsby Cloud: 1 (0.14%)
- Openbsd Httpd: 1 (0.14%)

Instead of using a proper DOM scraping library or anything, I just search the headers and page text. Not the most efficient or accurate, so if you find an issue please let me know! You can see my source code [here](https://paste.maxleiter.com/post/17dd30b8-4fd2-4270-a8a4-c6aab73a0211), although I'd recommend just doing it yourself from scratch and not scarring your eyes.

Thanks to Hacker News user retSava for [this comment](https://news.ycombinator.com/item?id=30954558) providing percentages, something I overlooked.


An analysis based on 700 personal websites

How hackers* run their sites


_[View this post on Drift](https://paste.maxleiter.com/post/9d77d452-8ccf-4056-89dd-9bf9f96dfc3c)_

I've wanted a Gist alternative for years, but it wasn't until I saw [this tweet](https://twitter.com/emilyst/status/1499858264346935297) I decided to sit down and build it:

> "What is the absolute closest thing to GitHub Gist that can be self-hosted? In terms of design and functionality. Hosts images and markdown, rendered. Creates links that can be private or public. Uses/requires registration. I have looked at dozens of pastebin-like things." - <a href="https://twitter.com/emilyst" style="color: var(--link);">@emilyst</a>

If your response to that is "why?", I recommend reading ['Why you should start self-hosting'](https://rohanrd.xyz/posts/why-you-should-start-self-hosting/) by Rohan Deshumkh. Also know that I have a habit of starting time consuming weekend projects to procrastinate school work, and this seemed like an especially fun one.

The primary goal of Drift is to capture the value proposition of GitHub. Syntax highlighting, markdown rendering, straight to the point. There are tons of self-hostable pastebins, and none target an experience like Gist. You can try a demo [here](https://drift.maxleiter.com).

Here's a screenshot of the authenticated homepage (don't worry, there's a light theme too):

<img src="/blog/drift/new.png" alt="A page showing the ability to enter a post title and two textboxes: file name and file content. You can also click 'add another file' or 'Create', which is a drop-down with multiple privacy options for creating posts." />

And here's a screenshot of viewing a post, which you can visit in your browser [here](https://paste.maxleiter.com/post/2ad57c13-4c40-4183-b41b-67e127fc5995):

<img src="/blog/drift/view-post.png" alt="A page showing a post title, the ability to download all files a ZIP archive, a dropdown to jump to specific files, and a file titled 'webpack.config.js' with javascript highlighted code." />

For prototyping, I used the [geist-ui library](https://geist-ui.dev) for the basic design components. It's _very_ JavaScript reliant, but I've already begun working on replacing it with in-house elements. So if you're reading this from Hacker News and were planning to complain it doesn't work &mdash; I'm sorry!

Rendering markdown, after multiple iterations, is done and stored on the server. This means that published posts can be rendered at build-time or on the server thanks to Next.js's SSR support. For editing, I've set-up a Next.js lambda function that receives markdown from the client and returns HTML.

Some other features are authentication, drag-and-drop file uploading, password protected posts, and support for GitHub Extended Markdown.

I'm particularly happy with the drag-and-drop uploading tied with the automatic syntax highlighting, as they lead to a great workflow for sharing files, which you can see a demo of here:

<video controls>
    <source src="/blog/drift/view-post-demo.webm" type="video/webm" />
</video>

The majority of these features are largely thanks to the Node and React ecosystems, so thank you to the maintainers of those projects.

If Drift is interesting to you, please feel free to contribute, regardless of skill level. There have already been numerous community contributions, including the logo and docker-compose. I've tried to keep it fairly simple, so the back-end is a simple Express server and the client is a Next.js React app. You can join #drift on [Libera.Chat](https://libera.chat) to get in touch. You can find Drift on GitHub [here](https://github.com/maxleiter/drift).


A self-hostable alternative to GitHub Gist and Pastebin

Introducing Drift

One of the most common questions I'm asked by my computer science friends and lower-level students is how they can contribute to an open-source project. In order for me to organize and share my thoughts I thought I'd write something here.

First off, it's a good idea! Contributing to projects is a fantastic way to build experience, connections, and improve a piece of software you use or rely on. I've grown immensely through maintaining my few projects and contributing to a hand full of others. I've gained experience in community management, team communication, code review, dependency management, and the list goes on. This post is focused on programming, but don't forget that issue management, documentation, user support, and bug reporting are all valuable ways you can contribute. 

That point about using open-source software is important. The first thing I tell my friends is they should first ensure they're using some before they attempt to contribute. There are few things that are more satisfying than fixing a bug that's been bugging you in a program written by someone else, and the motivation that provides is not inconsequential[^1]. As a maintainer, contributor, and extensive procrastinator I've seen and felt lack of motivation and burn-out from multiple perspectives, and know how daunting making a contribution can be. So to give you some ideas, here are some applications I use that you may want to try using (or may already use!), and a checklist for how to get started contributing to them:
- [Firefox](https://www.mozilla.org/en-US/firefox/new/) (really, it's [(in some cases)](https://arewefastyet.com/mac/benchmarks/overview?numDays=365) as fast as Chrome now! Plus it helps you escape _the Alphabet_.)
- [GIMP](https://www.gimp.org/) (GNU Image Manipulator Program, a free version of Photoshop.)
- [VS Code](https://github.com/microsoft/vscode) (note that most of it is open-souce, but parts are not.)
    - See [VSCodium](https://github.com/VSCodium/vscodium) if you want a VS Code fork without Microsoft telemetry and licensing

And loads more. I didn't even mention the vast number of open-source software libraries and frameworks you likely already use. Maybe [Next.js](https://nextjs.org), [Vue](https://vuejs.org), or [Flask](https://github.com/pallets/flask) are of interest to you, just to provide a few examples. And below is my framework for getting started.

### The steps
1. **Find a project and feature or bug to work on**: find one from experience or on their issue tracker/mailing list. Targeting a bug that bothers you or a feature you personally want is ideal due to the motivation aspect mentioned above. If the project is on GitHub these may be in the Milestone or Discussion pages. [GitHub Explore](github.com/explore) filtered to languages you know or are interested in learning is a great place to start.
2. **Search for prior work or discussions**: it's important your changes align with the maintainers vision, and you should double check that no one else is working on it. If they are or previously have, you can offer to team-up or ask for their advice.
3. **Familiarize yourself with the code base**: depending on the size, it may not be feasible or sensible for you to grok the entire code base. Instead, try to learn just the parts you need. Feel free to ask the maintainers after searching the documentation and using the below tips if you need help:
   * Read the README and CONTRIBUTING files, if they both exist[^2]
   * Use a package explorer or the Unix `find` utility to find directories and files of interest
   * Use `git grep` to find identifiable or interesting messages/logs/strings in the code (an error alert's text, for example)
   * Use `git log` to explore commits
   * Use `git blame` to find out who to email or contact with questions
      * You can also check the README or look for a COMMUNITY file to find where to ask
4.  **Get crackin'**: Work on the task, reaching out to the maintainers and/or community for help if necessary. Always be courteous, patient, and as clear as possible. Code samples and reproducible cases are king.
5. **Submit your work**: Most likely, submitting your completed work will be done via a mailing list or over a code forge like GitHub and BitBucket. Refer to their documentation and the project's documentation to determine how to submit your changes. 
6. **Wait, Fix, Repeat**: It's likely you'll need to address some comments and make some changes to your initial work. That's okay! Address their comments and send it back to them. Few things feel worse than wasting a reviewers time (especially a volunteer like in many open-source projects), so be sure you self-review your code like you (hopefully) would an English paper.[^3]

### A quick example:
...which you can read more about in [my dedicated post](/blog/MSHW0184).

1. I wanted ambient light support on my Surface Pro 3 running Linux
2. I searched Google for information and luckily found [this issue and repo](https://github.com/linux-surface/linux-surface/issues/121#issue-580967766):
![Image of the linked github issue](/blog/foss/github-issue.jpg)
3. I searched the <abbr title="Linux Kernel Mailing List">LKML</abbr> for previous examples of minor driver adjustments and joined the #linux-surface IRC channel to talk with the other contributors to hear their ideas. 
4. After a few hours and with some help from IRC I determined how to have the device registered using the existing driver and pushed my code to GitHub.
5. Once the code was reviewed by a few members of linux-surface I submit my patch set to LKML.
6. It was released in Linux 5.11 🎉

### In short

* Read the documentation
* Find an interesting problem to tackle that motivates you
* Discover and grow comfortable with your tools for grepping and exploring unfamiliar code bases 
* Don't be afraid to reach out to the maintainers and community; develop communication skills

[^1]:. <small>One of the few better feelings is fixing a bug in software you made that someone else reported.</small> [⏎](/blog/contributing-to-oss#ref:1)
[^2]:. <small>If the README does not exist, consider that a red flag. If the CONTRIBUTING file does not exist, consider asking the maintainers if you could help draft one.</small> [⏎](/blog/contributing-to-oss#ref:2)
[^3]:. <small>If you haven't worked professionally in CS yet, this is likely your first code review, and they're highly prevalent in the industry, so try extra hard to learn from your mistakes and take note of what you like and dislike about the review left for you.</small> [⏎](/blog/contributing-to-oss#ref:3)


A small guide to finding projects and contributing changes

How to start contributing to open-source projects


Today, the open-source maintainer [Marak](https://github.com/Marak) intentionally [bricked two popular JavaScript libraries](https://www.bleepingcomputer.com/news/security/dev-corrupts-npm-libs-colors-and-faker-breaking-thousands-of-apps/) (with ~25 total million weekly downloads) in such a way that they broke dependents software. There's nothing that npm or any other public registry could've done to have prevented this; the release was indistinguishable from a regular update, unless you looked at the code. This is not the first time an npm dependency has [gone rogue](https://qz.com/646467/how-one-programmer-broke-the-internet-by-deleting-a-tiny-piece-of-code/) and [caused havoc](https://github.com/dominictarr/event-stream/issues/115) due to supply chain problems, and it certainly won't be the last. And so the defensive role falls to you, the developer.

### Pinning dependencies

My recommendation is to **pin your dependencies**. If you're unfamiliar with what this means, you should first be familiar with [semantic versioning](https://semver.org/). In short, pinning dependencies means the _exact_ version specified will be installed, rather than a dependency matching the range criteria. Here's an example:

```json
{
  "dependencies": {
    "react": "17.0.2", // installs react@17.0.2 exactly. I recommend this.
    "react": "^17.0.2", // installs the latest minor version after .0 (so 17.*.*)
    "react": "~17.0.2" // installs the latest patch after .2 (so 17.0.*)
  }
}
```

To automatically accomplish this in your projects, you can add `save-exact=true` to a `.npmrc` file, or use `--save-exact` when adding the dependency via npm (or `--exact` via yarn).

If you do this, I also recommend some sort of dependency management so you stay up-to-date. I personally use the [renovate](https://github.com/renovatebot/renovate) bot for my GitHub projects.

### What about lockfiles?

You may have noticed npm and yarn generate `package-lock.json` and `yarn.lock` when you run `npm i` and `yarn`, respectively. The lockfiles allow every version of every sub-dependency to be pinned, while modifying the package.json only guarantees we pin the immediate dependency (which may not pin its own dependencies).

One problem with relying on lockfiles is that they and their semantics are confusing. In my experience, many new-to-npm users expect `npm i` to function like `npm ci`, and are unaware of the differences. `npm i` can update `package-lock.json`, whereas `npm ci` will only read from it.

> Tip: You almost always want to use `npm ci`

Meanwhile, with yarn, `yarn install` will install the version in the yarn.lock, regardless of the version in the package.json. Good for security? Sure. Good for the developer experience? Not so much. You need to use `yarn upgrade <package>` in order to fetch the version in the package.json if it's more recent than specified in the yarn.lock. It's now far more difficult to determine _when_ something is updated. If you've ever found yourself staring at a yarn.lock diff you'll know what I mean.

Lockfiles are good tools, but can be difficult and unintuitive to work with.

### In conclusion

Use lockfiles for pinning transitive dependencies, but have your package.json be the source of truth. Pin your dependencies so you have a human-friendly, readable method to audit your dependencies and ensure a specific version is installed. Automate some process to make sure you remain up-to-date.

If you disagree or have comments, feel free to [email me](mailto:maxwell.leiter@gmail.com) or reach out on [Twitter](https://twitter.com/max_leiter).


A guide on how to pin your dependencies and why you may want to

Pin your npm/yarn dependencies


In the off-chance you're reading this today, happy new year! If you're reading this later, I hope $CURRENT_YEAR is treating you well. 

Before this post, I kept a list of my programs in my iCloud in case my computer broke or I was setting up a work laptop. After some recent events, I trust iCloud less than I once did, and figured the list can live here instead. Like the rest of my blog, this exists for me but hopefully you find it useful too. I plan to write an Arch Linux version of this soon. 

I try to use open-source where I can. If you know of an alternative to the few closed applications I use, please let me know!

- [Firefox Nightly](https://www.mozilla.org/en-US/firefox/channel/desktop/)
    - [Chrome](https://www.google.com/chrome/) for testing sites
- [VisualStudio Code](https://code.visualstudio.com/)
- [iTerm 2](https://iterm2.com/) 
- [BetterTouchTool](https://folivora.ai/) allows advanced customization of the touchbar  ($9 after 45 days)
    - [GoldenChaos preset](https://community.folivora.ai/t/goldenchaos-btt-the-complete-touch-bar-ui-replacement/1281)
    ![Image of the GoldenChaos touchbar layout](/blog/macos/touchbar.jpg)
- [Homebrew](https://brew.sh/) is a package manager
    - Handles installing Xcode developer tools
- [Rectangle](https://rectangleapp.com/) lets you resize and snap windows with your keyboard
    ![Image of the Rectangle settings showing it has many options](/blog/macos/rectangle.jpg)
- [Fish](https://fishshell.com/) is user-friendly shell (seriously, I hate zsh/bash now)
    - [Fisher](https://github.com/jorgebucaran/fisher): Fish plugin manager
    - [fish-nvm](https://github.com/jorgebucaran/fish-nvm): [nvm](https://github.com/nvm-sh/nvm) wrapper
- [NextDNS](https://nextdns.io/) is a secure DNS service (I downloaded the macOS client from the App Store)
- [LastPass](https://www.lastpass.com/) is my password manager, but I'm currently looking to start self-hosting.
- [Insomnia](https://insomnia.rest/) is my favorite REST client
- [IINA](https://iina.io/) is a nice media player 
- [VIA Configurator](https://caniusevia.com/) configures my keyboard
- [Lagrange](https://github.com/skyjake/lagrange) for viewing Gemini articles
- [yarn](https://classic.yarnpkg.com/lang/en/docs/install/#mac-stable) is my node package manager of choice
- [MySQL Workbench](https://www.mysql.com/products/workbench/) for managing my few MySQL servers
- [TeXMaker](https://www.xm1math.net/texmaker/) for the rare times I need to write LaTeX
- I'm going to try and use the Slack and Zoom browser versions
- Qemu: `brew install qemu`
- thefuck: `brew install thefuck`, command line correction tool
    - Add `thefuck --alias | source` to `~/.config/fish/config.fish`
- imagemagick: `brew install imagemagick`
- ffmpeg: `brew install ffmpeg`


My macOS programs and setup


I've been messing around with a React implementation of The Lounge lately (for no real reason except that I can) and wanted a functional way to use [Mousetrap](https://craig.is/killing/mice), which TL already uses.  The below hook let me replace the Vue use of Mousetrap (which was pretty much vanilla JS) in a React-like fashion. For bonus typing, add `@types/mousetrap` to your project.

Usage is pretty simple:
```ts
useMousetrap("escape", (evt, combo) => {
	evt.preventDefault
}, "keypress")
```

```ts
import mousetrap from "mousetrap"
import { useEffect, useRef } from "react"

const useMousetrap = (
	handlerKey: string | string[],
	handlerCallback: (evt: KeyboardEvent, combo: string) => void,
	evtType?: "keypress" | "keydown" | "keyup",
) => {
	let actionRef = useRef(handlerCallback)

	useEffect(() => {
		mousetrap.bind(
			handlerKey,
			(evt: KeyboardEvent, combo: string) => {
				typeof actionRef.current === "function" && actionRef.current(evt, combo)
			},
			evtType,
		)
		return () => {
			mousetrap.unbind(handlerKey)
		}
	}, [evtType, handlerKey])
}

export default useMousetrap
```

A quick TypeScript React hook for Mousetrap.js

useMousetrap()


I've had a server on [Creeper Host](https://creeper.host) for around eight years now, and have used it for small side projects and hackathons. Lately, I've been trying to  automate more of my life and discovered that the API their in-house control panel uses is [available for general use](https://creeperhost.docs.apiary.io/). I'm making this post in case someone else ever wants to interact with their API via JavaScript. Maybe someday I'll create a proper repository, but for now my wrapper is incomplete and it's easier to just include here. It was also a good chance to write some TypeScript from scratch, something I haven't had the opportunty to do very much of.

To get started, you'll need to generate a Developer Token on the [control panel](https://creeperpanel.com). Navigate to the `Sub-accounts` page and generate a new API key at the bottom of the page:

![Screenshot of the Creeper Host control panel with a blue 'Generate Key' button](/blog/creeperhost/apiKey.png)

Also, install [axios](https://axios-http.com/) (or change the below code to your favorite request library, I don't care):
```bash
    yarn add axios
```
Then, incorporate these two files:

```typescript title=Client.ts collapsible
import axios, { AxiosRequestConfig } from "axios";
import { InitializationOptions, MetricResponse, RestartResponse } from "./types";

export default class Client {
    private instance: string;
    constructor({ apiKey, apiSecret, apiUrl = 'https://api.creeper.host', instanceId}: InitializationOptions) {
        axios.defaults.baseURL = apiUrl;

        axios.defaults.headers.common['key'] = apiKey;
        axios.defaults.headers.common['secret'] = apiSecret;
        axios.defaults.headers.common['Content-Type'] = 'application/json';

        this.instance = instanceId;
    }

    private async request<T = any>({ method = "GET", apiRoute, body }: { method: "GET" | "POST", apiRoute: string, body?: any}) {
        const config: AxiosRequestConfig = {
            method,
            url: apiRoute,
            data: body
        }

        console.log(`[${method}] ${apiRoute}`, body ? `\t ${JSON.stringify(body)}` : '');

        const request = await axios.request<T>(config);
        return request.data;
    }

    public os = {
            getram: async () => {
                return this.request<MetricResponse>({ method: "GET", apiRoute: "os/getram" });
            },
            getssd: async () => {
                return this.request<MetricResponse>({ method: "GET", apiRoute: "os/getssd" });
            },
    }

    public minecraft = {
        restartserver: async () => {
            return this.request<RestartResponse>({ method: "POST", apiRoute: "minecraft/restartserver", body: { instance: this.instance} });
        },
    }
}
```

```typescript title=types.d.ts collapsible
export type MetricResponse = {
    status: 'success';
    free: number;
    used: number;
} | {
    status: 'error',
    message: string
}

export type RestartResponse = {
    status: 'success';
    message: string;
} | {
    status: 'error',
    message: string
}
```

Finally, create an instance via `new Client({ apiKey, apiSecret, instanceId });`
You can use it by finding what you want to call on the Creeper Host docs and accessing that on the client; I purposefully used the same naming scheme. For example,
```typescript
Client.os.getram(): Promise<MetricResponse>
```
corresponds to the [https://api.creeper.host/os/getram](https://creeperhost.docs.apiary.io/#/reference/0/server/get-server-ram-details/200?mc=reference%2F0%2Fserver%2Fget-server-ram-details%2F200) endpoint.

I removed some methods from the above to avoid cluttering this page, but it's straight forward to add your own. If you really want to use this, contact me and I can set up a repo for us to collaborate. Also, if you have suggestions on how I can improve this, let me know via [email](mailto:maxwell.leiter@gmail.com) or on [Twitter](https://twitter.com/Max_Leiter).

In case someone also wants a quick wrapper for interacting with the Creeper Host REST API

Creeper Host API wrapper in TypeScript


Today I found myself once again trying to run a pull request that was created in a different GitHub repository. If it was in the same repo, it would be a simple `git checkout`, however because GitHub insisted on the creation of "forks" I now need to go through the extra steps of fetching that specific ref. Here's what I do:

```bash
git fetch https://github.com/${team}/${respository}.git refs/pull/${prId}/head
git checkout FETCH_HEAD
git rebase master # or main
```

Just replace `team`, `repository` and `prId` and you're all set. 

I picked this script up from The Lounge: https://github.com/thelounge/thelounge/blob/master/scripts/run-pr.sh. It's a more complete example if you want to start using a script like this. Notice the [`shift`](https://tldp.org/LDP/Bash-Beginners-Guide/html/sect_09_07.html) and bash substitution ([`$@`](https://stackoverflow.com/a/3898681)) at the end of it —  these allow you to pass in command-line arguments to `yarn start` (or whatever your run script is).



A quick script I use for checking out and running pull requests

run-pr.sh


I received my [Framework Laptop DIY edition](https://frame.work) a few days ago and have been setting it up software-wise. I have it running Manjaro Linux with the Sway window manager. This is my first time using a Wayland desktop, and oh has it been a learning experience. This post will be largely about the hardware, but I plan to make one about the software once I'm more happy with my setup.

Here's what I got:
* Framework Laptop DIY Edition
* 16GB (2 x 8GB) DDR4-3200
* Intel® Wi-Fi 6E AX210 No vPro
* 1TB - WD_BLACK™ SN850 NVMe™
* USB-A Expansion Card
* USB-C Expansion Card x2
* HDMI Expansion Card

I bought everything from the Framework store (at a slight markup of ~$80 for the RAM, SSD, and wifi card), but I'm happy to support them and for the convenience of knowing it would work properly was well worth it. 

## The Good
* Well crafted body. I was not expecting a premium build quality from a startup trying to create an upgradeable laptop, but wow they excelled.
* It's *really light*. It's just 2.8 pounds, compared to my 13" Macbook Pro's 3.02. You wouldn't think that's a big difference, and maybe you wouldn't notice, but I sure did.
* A solid keyboard. Most non-Mac laptops I've tried have awful keyboards. It's not as rigid as an Apple non-butterfly board, but it's close. Definitly usable.
* Modular expansion ports (via pass-through to USB-C) are a fantastic idea. I can't wait for 3rd party ones to be released. 
* Hardware switches for the camera and microphone.
* Beautiful glossy screen. I haven't used it extensively outside, but it's worked well enough for me (especially at full brightness).
## The Bad
* There are only 3 preset levels of keyboard backlight you can switch between: off, on, and half. Perhaps my Mac spoiled me, but I'm used to having more fine-tuned control over it.
* Installing the wifi card was difficult. It took me twice as long to install the WiFi as it did to setup the rest of the computer. They acknowledge this in their installation instructions, but othes seem to also be having problems:
![Image of the Framework setup guide comments showing 6 people also having difficulty](/blog/framework/comments.png)
* Removing expansion ports requires far more force than installing them. Feels a little awkward.
* 12 seconds of pressing the power button to hard reboot. Not that big of a deal, but definitely feels *way* too long.
* Why does the screen need to swing open 185°?

## The Ugly
* This isn't necessarily due to the hardware, but the battery life on Linux currently requires a little finessing to be reasonable. I'm sitting at ~4h of moderate use after tweaking numerous configs and following multiple different sets of instructions from around the internet. This isn't good enough for me to take on campus for class, but it's great for doing work around the house.
* Lacks the ability to set charging thresholds. It's [being worked on](https://community.frame.work/t/battery-charge-optioms/755/3), but at the moment it doesn't seem possible. 
* A strange 2256x1504 resolution. Why couldn't they have chosen something more standard? Although I think my issues with this are mostly due to Linux / Wayland. Maybe I'll get used to 3:2.
* It requires a little extra care to open the laptop without sliding it (perhaps due to its light weight).

## In conclusion
I'll let my Tweet from a few days ago sum it up:

[![Image of the Framework setup guide comments showing 6 people also having difficulty](/blog/framework/twitter.png)](https://twitter.com/max_leiter/status/1455642990274248706)

My thoughts on the Framework Laptop's hardware

Impressions of the Framework Laptop


A couple of a weeks ago I picked up a Surface Pro 7 (i3 1.2 mhz) at a Black Friday sale. I love making devices run software they shouldn't, so I got to work dual-booting Linux on it. To my surprise, almost everything worked with the default Fedora 33 kernel, not including the touchscreen, the ambient light sensor, and the camera. After compiling and loading the great [linux-surface](https://github.com/linux-surface/linux-surface) kernel the touchscreen started to work but I found a [GitHub issue](https://github.com/linux-surface/linux-surface/issues/121) someone had made detailing that the ambient light sensor (a MSHW0184) isn't detected. This normally wouldn't matter a lot, but I'd discovered that GNOME supported adjusting the screen brightness based on the ambient light through [iio-sensor-proxy](https://gitlab.freedesktop.org/hadess/iio-sensor-proxy/).

I knew nothing (and still know very little) about the Linux kernel or drivers, but this seemed like a great place to start. Luckily, GitHub user archseer discovered that the MSHW0184 registers align with the APDS9960 device, which already has an upstream kernel driver, and he mentioned all that should be needed is a small change to allow the driver to detect the new device.

Here I realized I had to do some research into how the kernel loads drivers. I knew that drivers could either be statically built into the kernel, or built as kernel modules so they can be dynamically loaded when they're needed. But how does the kernel know when to load specific drivers for certain hardware? You register the ID with a matching table.

Initially, I tried adding the MSHW0184 device ID to the existing match table in the APDS9960 driver for the i2c protocol. This consisted of the following one-line change:

```c
static const struct i2c_device_id apds9960_id[] = {
                    { "apds9960", 0 },
+                   { "MSHW0184, 0 }
                    {}
}
```

However, this didn't work and I realized the conventions seemed a little odd: no other i2c device ids in other drivers contained capitals or were ambient light sensing devices. Thankfully, someone on IRC helped me out:

```
00:53 &#60;djrscally&#62; That's an acpi ID 
00:53 &#60;djrscally&#62; You probably need to add an ACPI match table
```

A few minutes later (well, probably closer to 30 minutes after compiling and testing the kernel on-device) I had the following, largely copied from other ACPI drivers:

```c

+ static const struct acpi_device_id apds9960_acpi_match[] = {
    +	{ "MSHW0184" },
    +	{ }
    +};
+ MODULE_DEVICE_TABLE(acpi, apds9960_acpi_match);

  static struct i2c_driver apds9960_driver = {
    .driver = {
        .name	= APDS9960_DRV_NAME,
        .of_match_table = apds9960_of_match,
        .pm	= &apds9960_pm_ops,
+       .acpi_match_table = apds9960_acpi_match,
    },
    .probe		= apds9960_probe,
    .remove		= apds9960_remove

```

I recompiled the kernel module, rebooted, and verified the driver was matched with lsmod and ensured the driver paired with the device by navigating to the IIO device (finding the path to the device took a lot more work than I'd like to admit) and reading in the `in_intensity_clear_raw` file:

```sh
 max@surface ~> cat sys/bus/iio/devices/iio:device0/in_intensity_clear_raw
    33
```

The joy I felt seeing that file exist and the output was monumental. I had something to work with!

I wasn't done yet though — GNOME still didn't show me an option to automatically adjust the screen brightness. After someone else verified they also had the device loaded with the modified driver but not in GNOME I determined the problem was somewhere in iio-sensor-proxy. I cloned the iio-sensor-proxy repository and started digging.

The first thing I always do when I clone a new repo is expand and quickly look over every folder (assuming the repo is a reasonable size) and that served me well here. I found the following file `80-iio-sensor-proxy.rules`:

```yml
# iio-sensor-proxy
# IIO sensor to D-Bus proxy

ACTION=="remove", GOTO="iio_sensor_proxy_end"

# Set the sensor type for all the types we recognise
SUBSYSTEM=="hwmon", TEST=="light", ENV{IIO_SENSOR_PROXY_TYPE}+="hwmon-als"
SUBSYSTEM=="iio", TEST=="in_accel_x_raw", TEST=="in_accel_y_raw", TEST=="in_accel_z_raw", ENV{IIO_SENSOR_PROXY_TYPE}+="iio-poll-accel"
SUBSYSTEM=="iio", TEST=="scan_elements/in_accel_x_en", TEST=="scan_elements/in_accel_y_en", TEST=="scan_elements/in_accel_z_en", ENV{IIO_SENSOR_PROXY_TYPE}+="iio-buffer-accel"
SUBSYSTEM=="iio", TEST=="scan_elements/in_rot_from_north_magnetic_tilt_comp_en", ENV{IIO_SENSOR_PROXY_TYPE}+="iio-buffer-compass"
SUBSYSTEM=="iio", TEST=="in_illuminance_input", ENV{IIO_SENSOR_PROXY_TYPE}+="iio-poll-als"
SUBSYSTEM=="iio", TEST=="in_illuminance0_input", ENV{IIO_SENSOR_PROXY_TYPE}+="iio-poll-als"
SUBSYSTEM=="iio", TEST=="in_illuminance_raw", ENV{IIO_SENSOR_PROXY_TYPE}+="iio-poll-als"
SUBSYSTEM=="iio", TEST=="scan_elements/in_intensity_both_en", ENV{IIO_SENSOR_PROXY_TYPE}+="iio-buffer-als"
SUBSYSTEM=="iio", TEST=="in_proximity_raw", ENV{IIO_SENSOR_PROXY_TYPE}+="iio-poll-proximity"
SUBSYSTEM=="input", ENV{ID_INPUT_ACCELEROMETER}=="1", ENV{IIO_SENSOR_PROXY_TYPE}+="input-accel"

ENV{IIO_SENSOR_PROXY_TYPE}=="", GOTO="iio_sensor_proxy_end"

# We got here because we have a sensor type, which means we need the service
TAG+="systemd", ENV{SYSTEMD_WANTS}+="iio-sensor-proxy.service"
```

As you might be able to figure out, each TEST file is checked for existence and is used to determine whether or not the device should be used by iio-sensor-proxy.

I hadn't seen any of the seemingly relevant files, in_illuminance_*, so I added my own line:

```yml
SUBSYSTEM=="iio", TEST=="in_intensity_clear_raw", ENV{IIO_SENSOR_PROXY_TYPE}+="iio-poll-als"
```

After another small iio-sensor-proxy change and running again the device was now discovered by iio-sensor-proxy! The full merge request can be seen [here](https://gitlab.freedesktop.org/hadess/iio-sensor-proxy/-/merge_requests/319). The option appeared in GNOME and I now have automatic adjusting brightness!

It kind of sucks though and isn't very consistent. As it turns out, intensity_clear != illuminance, which is what most programs expect from ambient light sensors, so I need to figure out and perform some math in iio-sensor-proxy to translate the RGBC values to lux.

If you've made it this far (or are here to get the code yourself), the modified driver (with basic proximity sensing support too) can be found here: https://github.com/maxleiter/MSHW0184.

Major thanks to everyone that helped me in the ##linux-surface IRC channel. It was great to finally get a little low-level with Linux. 

---
*This post was originally written on the old maxleiter.com, and formatting has slightly adjusted

Adding ambient light support to Linux and GNOME

<details>
    <summary>Please read</summary>
    While the content below may be useful to some, the Cydia repository is no longer available due to the maintaince overhead and my loss of interest. If you still want X11 on iOS/iPadOS, check out the <a href="https://github.com/ProcursusTeam/Procursus" style="color: var(--link)">Procursus project</a>.
</details>

I'm excited to announce that X11 is coming soon to iOS. Most (see below) packages and dependencies for a fully functioning X11 desktop system have been compiled and are available on Cydia for iOS 11+. All packages have been compiled for arm64 and have been tested on iOS 12.4 and iOS 13.1. This requires a jailbroken device.

![Image of X11 on iOS](/blog/X11/x11.png)
[Image of programs running on device.](/blog/X11/onipad.jpg)

This site will serve largely as documentation for building yourself. ~You can add the Cydia repo below for the deb packages. Please let me know if you run across any issues with the debs; it's likely I messed up including a library or something like that. (These aren't done just yet.)~

## How it works

At the moment, a virtual screen is accessed via a VNC client to an Xvnc instance running on the iDevice. If you're unfamiliar, Xvnc is an X server with a virtual screen that can be accessed via VNC. The best part of this is no drivers are required: it's all handled by Xvnc.

## Why

Largely just because I can. Also, I want to turn my iPad into a proper development environment, and a windowing system helps with that. It's a powerful machine with a Unix-like OS, so X11 seemed like a reasonable project. X11 allows running arbirtary applications like browsers and IDEs, assuming you can make them compile.

## Current Features
 - X11 on iOS via Xvnc
 - Working window managers (jwm / twm / fluxbox)
 - Text editor (adie)
 - Image editor (azpainter)
 - OpenGL (via Mesa)
 - Loads of other libraries, tools, and applications.

## Building instructions
Before you start, be sure to have an iOS SDK located at `/usr/share/iPhoneOS.sdk` for sbingner's llvm-10 to function. You can get the SDKs from theos.

The following tools/libraries are required to build the packages (unless you choose to build these yourself): 

From MCApollo's repository:
 - Gettext
 - Glib
 - libffi
 - libxml2
 - m4
 - OpenSSL
 - perl
 - PkgConfig
 - libiconv
 - Python @ 3.7
 - readline
 - zlib
 - clang-10
 - Darwin CC Tools
 - Bison
 - Flex
 - libstdc++ (C++ Standard Library symlink)
 - automake
 - autoconf
 - ninja
 - libpng
 - gperf


 In general, you can follow the instructions from [Beyond LinuxFromScratch](http://www.linuxfromscratch.org/blfs/). This project is based on 9.0, with version differences or code modications marked with ⚠️ below. Applications and libs marked with ❗️ means unavailable on iOS or I was unable to build them. Empty notes means compiles and works as-is from BLFS. Additionally, all of the packages are available (generally as dylibs) on the Cydia repo linked above.

|Name|Version|Notes|
|--- |--- |--- |
|util-macros|1.19.2||
|xorgproto|2019.2||
|libXau|1.0.9||
|libXdmcp|1.1.3||
|xcb-proto|1.13||
|libxcb|1.13.1||
|Freetype|2.10.1||
|Fontconfig|2.13.1 ⚠️|Requires modifying stdlib.h in SDK to allow system calls. Bug with patch available here.|
|xtrans|1.4.0||
|libX11|1.6.9||
|libFS|1.0.8 ⚠️|Need to remove some code from the libtool file. The enviroment variables aren't populated on iOS so a generated bash command is wrong. Check the output of ./configure to pinpoint the line number.|
|libICE|1.0.1||
|libSM|1.2.3||
|libXScrnSaver|1.2.3||
|libXt|1.2.0||
|libXmu|1.1.3||
|libXpm|3.5.13||
|libXaw|1.0.13||
|libXfixes|5.0.3||
|libXcomposite|0.4.5||
|libXrender|0.9.10||
|libXcursor|1.2.0||
|libXdamage|1.1.5||
|libfontenc|1.1.4||
|libXfont2|2.0.4||
|libXft|2.3.3||
|libXi|1.7.10||
|libXinerama|1.1.4||
|libXrandr|1.5.2||
|libXres|1.2.0||
|libXtst|1.2.3||
|libXv|1.0.11||
|libXvMC|1.0.12||
|libXxf86dga|1.1.5||
|libXxf86vm|1.1.4||
|libpciaccess|1.0.12 ❗️|Unsupported OS|
|libdmx|1.1.4||
|libxkbfile|1.1.0||
|xcb-util|0.4.0||
|xcb-util-image|0.4.0||
|xcb-util-keysyms|0.4.0||
|xcb-util-keysyms|0.4.0||
|xcb-util-renderutil|0.3.9||
|xcb-util-wm|0.4.1||
|xcb-util-cursor|0.1.3||
|Mako|1.1.0|If you can't build yourself, try using pip|
|Mesa|0.52.1 ⚠️|Set DRI drivers to swrast and set gallium drivers to empty. I manually modifed meson_options.txt. Also symlink m4 to /opt/local/bin/gm4. I had to remove an __APPLE__ check in /src/mesa/main/texcompress_s3tc_tmp.h so it used the GL library instead of the macOS OpenGL one. Also, be sure to specify a minimum iOS version so thread-local support works with something like -miphoneos-version-min=11.2.|
|xbitmaps|1.1.2||
|iceauth|1.0.8||
|luit|1.1.1|Run sed -i -e "/D_XOPEN/s/5/6/" configure|
|mkfontdir|1.0.7||
|mkfontscale|1.2.1||
|sessreg|1.1.2||
|setxkbmap|1.3.2||
|smproxy|1.0.6||
|x11perf|1.6.1||
|xcursorgen|1.0.7||
|xdpyinfo|1.3.2||
|xev|1.2.3||
|xhost|1.0.8||
|xinput|1.6.3||
|xkbcomp|1.4.2||
|xkbevd|1.1.4||
|xkbutils|1.0.4||
|xkill|1.0.5||
|xlsatoms|1.1.3||
|xlsclients|1.1.4||
|xmessage|1.0.5||
|xmodmap|1.0.10||
|xpr|1.0.5||
|xprop|1.2.4||
|xrandr|1.5.1||
|xrdb|1.2.0||
|xrefresh|1.0.6||
|xset|1.2.4||
|xsetroot|1.1.2||
|xvinfo|1.1.4||
|xwd|1.0.7||
|xwininfo|1.1.5||
|xwud|1.0.5||
|startup-notifcation|.12||
|xterm|351||
|FLTK|1.3.5 ⚠️|Need to remove some -U__APPLE__ calls. Disable tests in Makefile.|
|tigervnc|1.10.1 ⚠️|No vncviewer. Disable it via CMake. Remove the if(NOT APPLE) check above the add_subdirectory(unix). Also remove the find_package(FLTK) check and remove the line add_subdirectory(tests) (as some tests require FLTK). It's important to build tigervnc before building Xvnc.|
|Xvnc|1.10.1 ⚠️|Add a fake Xplugin.h to fool /unix/xserver/miext/rootless. Modify rootlessWindow.c to check for "Xplugin.h" instead of <Xplugin.h>. Also, remove the -z, now characters from /unix/xserver/hw/vnc/Makefile.in, where it's assigning libvnc_la_LDFLAGS.|
|Glib|2.62.4 ⚠️|Disable cocoa and carbon support in build.meson. Had to fake crt_externs.h. Remove the if host_system == 'darwin' check in glib/meson.build.|
|LuaJIT|2.1.0|https://github.com/rweichler/luajit-ios|
|OpenJPG|2.3.1||
|poppler|0.84.0||
|check|0.11.0||
|pango||working on it|
|EFL|1.23.3|working on it|
|compton|git v0.1 beta g316eac0||
|FOX toolkit|1.7.67|Contains Adie (text editor), a calculator, and Shutterbug (screenshots)|
|azpainter|4bf18c8||

---
*This post was originally written on the old maxleiter.com, and formatting has slightly adjusted

A guide on how to compile the X Window System for iOS

X11 on iOS

Patched, compiled, and packaged X11 for iOS devices.

A self-hostable and open-source alternative to GitHub Gist and Pastebin.

Drift

Self-hosted, always-on IRC client built with Node.js, Vue, and other web technologies.

The Lounge

A TypeScript wrapper for SortableJS that's built for Vue 3.

SortableJS-vue3

Open-source unix-like operating system for z80-based calculators written entirely in z80 asm.

KnightOS

HackSC is Southern California's largest hackathon with over 800+ attendees.

HackSC

A helper IRC bot for The Lounge's IRC channel.

thelounge-bot

Support for the MSHW0184 device (used in Microsoft Surfaces) in the Linux kernel.

MSHW0184 driver for Linux kernel

A 2kb JavaScript library for generating HTML trees from JSON.

jsonTree

Annie is the official app for the University of Southern California's Annenberg Media Center.

Annie

A React tool for running and visualizing a fictional BASIC language for a class.

BASIC visualizer

A quick tool for viewing recent President's executive orders.

EO-tracker

A web app for calculating artillery distances in the video game Hell Let Loose.

easyarty.com

A Raycast extension for managing Vercel via its REST API.

Vercel Raycast

A React and d3.js tool for visualizing a user's GitHub activity.

Max Leiter

Full-stack developer

About me

My projects

My posts