Testing device orientation (gyroscope) on localhost using Vite

I'm making a tilt component atm and wanted to make it respond to gyroscope (device orientation) changes. there were some caveats with testing it locally so I decided to write this post to explain it.

1. Device Orientation Event

To detect device orientation (gyroscope) changes, you need to add an event listener for the deviceorientation event. this is how it's done in React using TypeScript:

const handleDeviceOrientation = useCallback(
  (e: DeviceOrientationEvent) => {
    // do something with `e.alpha`, `e.beta`, and `e.gamma`
  },
  []
);

useEffect(() => {
  window.addEventListener(
    'deviceorientation',
    handleDeviceOrientation
  );
  return () =>
    window.removeEventListener(
      'deviceorientation',
      handleDeviceOrientation
    );
}, [handleDeviceOrientation]);

We can then get the rotation values in degrees around each axis from the event object:

• e.alpha : rotation around the Z axis
• e.beta : rotation around the X axis
• e.gamma : rotation around the Y axis

2. Testing in Chrome

To test device orientation in Chrome, you can use the Sensors tab in Chrome Devtools. to access it:

1. F12 to open DevTools
2. Three dots->More Tools->Sensors
3. In the Orientation section, you can drag/rotate the 3d phone model around to change the device orientation and see the effect in your application:

3. Testing on your phone

Now you probably want to test your application on your phone to see how it actually works. First, you need to make your dev server accessible to your local network. To do that, run the dev server with the -- --host flag. (no, it's not a typo!)

npm run dev -- --host

Now your dev server is exposed to your local network and it should list the IP addresses/ports it's listening to, like:

➜  Local:   http://localhost:5173/
➜  Network: http://192.168.1.x:5173/

Make sure your phone is connected to the same network as your PC and open the listed address/port. it should connect and show your application. (I usually do this to test all my applications on my phone in addition to Chrome's responsive view mode)
Now, you will notice that the device orientation event doesn't work on your phone!

4. Vite dev server with HTTPS

Your phone doesn't give access to the device orientation (gyroscope) sensor when your app is served under the HTTP protocol. It has to be served under HTTPS for it to work!
To run your dev server in HTTPS, do these steps:

1. Install the @vitejs/plugin-basic-ssl package:

npm i @vitejs/plugin-basic-ssl

1. Edit your vite.config.ts file to reflect these changes:

import basicSsl from '@vitejs/plugin-basic-ssl'
plugins: [basicSsl()] // add basicSsl() to the plugins array

If you're using React, your vite.config.ts file should look something like this now:

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import basicSsl from '@vitejs/plugin-basic-ssl';

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [react(), basicSsl()],
});

Now when you run the npm run dev -- --host command, your dev server will run under the HTTPS protocol and the listed addresses will begin with https://.
After going to the listed address/port on your phone, you will see this warning message: Your connection is not private (NET::ERR_CERT_AUTHORITY_INVALID)
Tap on Advanced and select the Proceed to ... (unsafe) option.

🎉 Congratulations! now you can test/debug device orientation (gyroscope) on localhost using your phone!