Vite on blog.iankulin.com

Getting Your Vite React App to Work on Github Pages

Fri, 26 Jan 2024 00:00:00 +0000

One of the many cool things about GitHub is GitHub Pages - the free web hosting Microsoft gives you while they vacuum up your code for CoPilot training. Each repository you keep there can have pages at <your-github-username>.github.io/<repo-name>

GitHub

To enable this, you need to go into the settings for the repository - look down the left for “Pages”.

It’s possible to have it based on a complicated GitHub action (where your build step happens on GitHub when you push your code), but the easiest thing is just to have it deployed from a branch. To do this you choose which branch (usually main) and whereabouts in the main branch your HTML is. The choices are in the root of your project, or in the /docs directory. I’ve chosen the /docs directory in the screenshot above, since my messy React project is in the root.

That’s all the GitHub set up we need. Now whenever I push my project to the main branch on GitHub, whatever is in the /docs directory will be uploaded to my GitHub page for this repo.

Vite/React

Now we need to make a couple of changes to our project to get this to work. The first is to tell Vite the “base directory” for the project which needs to be the repo name you’ve used on GutHub.

This is written into the index.html that is built as part of this process. If it’s not there, then any browser accessing your index.html on gh-pages won’t be able to find your JavaScript, and the user will be left looking at a blank white page instead of your amazing app.

My process from this point, is to build the project with npm run build. By default, this creates a /dist directory in your project (which is already added to .gitignore) and puts the project artifacts (the HTML, JavaScript, CSS and any images) into it. I then manually copy the artifacts over to the /docs directory of the project and push it up to GitHub to be published - which takes two or three minutes.

I like this manual step of copying the files over so that publishing is an intentful action on my part, and also, for solo projects I generally just work out of the main branch rather than on feature branches that then get PR’d into main. If you did want the process to be more CI/CD flavoured, you can just make another change the vite.config.ts file to have your builds go straight to the /docs folder.

import { defineConfig } from 'vite'import react from '@vitejs/plugin-react'// https://vitejs.dev/config/export default defineConfig({ base: "/mosh-expense/", plugins: [react()], build: { outDir: 'docs', }})

Once all that’s working, and you’ve pushed your changes and waited a minute or two, your project should be live to the world on github.io

If you want users browsing your repo to find the live version, it’s worth editing your repository about settings to point to it.

React - a To Do Example

Mon, 08 Jan 2024 00:00:00 +0000

Since I’m on a roll making different versions of the To Do app, this might be a good time to talk about React. React is one of the giants of front end libraries. It’s based on a few big ideas - and to work effectively in React you need to wrap your head around these.

Overview

Components - when you are developing in React, the starting point of your build is to decompose the user interface in to logical pieces. These components (comprising a mixture of HTML and Javascript) will be the building blocks of your app. In a good composable architecture components are reusable, and that is true for React (there are several sources of components you can pull in). For example, if you created some sort of special slider for your app, it is possible to reuse that quite easily.

Declarative - this was one of the big barriers when I was learning SwiftUI. The UI is just described. It’s not a big step when you’re coming from HTML - all that is is a description of the user interface. The next step of this is that React deals with using the state of your data model to update the UI. This means that these state-UI connections are made very explicit (which I like) and protected. For example if there’s a counter on a web page, you can’t change the HTML of the page to increment the counter, and in fact, you can’t directly change the counter. These things are wrapped up so React can manage them, and you have to play by React’s rules.

Virtual DOM - since each component knows what state it depends upon, and changing that state causes the component to be redrawn, it quickly gets expensive with parts of the page being reloaded. To improve performance, and reduce often unneeded flashes of content loading, React keeps a copy of the DOM and makes changes to it rather than the real DOM. Since this is instrumented, React can easily see what changes really need to be percolated to the browser DOM and can manage how that happens in the most efficient way. Sometimes I think I know what I want to happen for something to be efficient but in React, it’s often not in your control, and you just need to trust the system.

Tooling

We’re leaving my comfort zone of straightforward development environments, along with the major benefit of working in Javascript. The complexity of the React system requires a build step to produce the production artifacts. Whether you use the standard Create-React, or Vite (as I did for this project) you get a system for bundling the code, mapping it (since for debugging you need a way to translate the source line that’s running back to the human readable source), and a development server to run the app while you’re working on it.

These things inevitably add to complexity and errors, and are the reason that big projects start to need tools like development containers to remove a pain point. Like anything, you get better with experience, but especially at the start there’s a developer cost involved. React is incredibly popular, so most people’s calculus on this is that the extra complexity in project management is made up for with improved developer experience.

In any case, I got started by typing npm create vite@latest . and then choosing React and Javascript. This created a starter project, and spun it up in the development server. In the package.json file it gives you, there is a build command that can be run with npm run build to create the output files. I had issues with the development server that serves up these frontend files - since I also needed to run a real server (the unchanged REST API server for Todo Items data from the earlier project) on a different port. Then it complained - thinking it was part of a cross-site scripting hack. To overcome it, I just built the production code for each round of testing - with such a little project this wasn’t a hardship. But when I did have an error to track, it pointed me to a line number that turned out to be about 20 pages of minified code.

Components

Just a little reminder of how this app looks so we can think about how we’re going to break it down. There is a list of todo items, each one has a button to delete it (which we do when it has been completed) then at the bottom there’s a little form to add a new item (by clicking the button or hitting enter) to the bottom of the list.

I ended up with three components - the App (every React app has one), the TodoList, and the AddTodoForm. Note that I could easily have had a forth component - the TodoItem. This is a bit of matter of taste - I probably would have if I wanted to do something fancier like editing in place - but for the current UX the cost of extracting out another component wasn’t worth the benefit.

Anatomy of a component

I claimed earlier that a component was it’s HTML and Javascript wrapped up together which, while a massive simpliciation, is a good place to start thinking about it. Every component is just a function that returns a bunch of (templated) HTML. We’ll start off by developing our AddTodoForm. At it’s simplest, it could be something like this:

function AddTodoForm() { return ( <form> <input type="text" name="todo_item" id="todo" required /> <button type="submit">Add</button> </form> );}export default AddTodoForm;

But this little form component can’t really talk to the world, where as we need it to add a todo item. First, let’s track any changes to the text field.

import { useState } from 'react';function AddTodoForm(props) { const [value, setValue] = useState(''); return ( <form onSubmit={handleSubmit}> <input type="text" name="todo_item" id="todo" value={value} onChange={e => setValue(e.target.value)} required /> <button type="submit">Add</button> </form> );}export default AddTodoForm;

This is an example of the very explicit management of state I was talking about earlier.

const [value, setValue] = useState('');

useState() is a React hook for managing state. This line gives us a getter (value) and setter (setValue) for this variable, and set’s its initial state to ‘’. If the value changes the component will be redrawn. React will know that the value has changed as this is built into the setValue() function where we never need see or worry about it. If you foolishly decided to side-step React and assign directly to value, I guess there’d be a runtime error, or even worse, no error and the management of the DOM state wuld fall into some type of chaos.

What we’re doing with this value (which I’m now realising is very badly named) is using it to collect the text input from out form. It’s constantly updated as the user types.

onChange={e => setValue(e.target.value)}

So that’s our value sorted, but of course we need to add it to our data model. This model is being managed at the App level so there’s a bit of juggling needed to get it out to there. This ‘plumbing’ cost is the downside of these types or framework, but it’s not really complex and quickly becomes routine.

We’ll start at the top, here’s the relevant code from App.jsx - our App component.

 const [todos, setTodos] = useState([]); const addTodo = (newTodo) => { fetch('http://localhost:3000/todos', { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify(newTodo), }) .then(response => response.json()) .then(data => { // Update the todos state with the new todo setTodos([...todos, data]); }); };

This useState hook should be starting to look familiar. We read the todos from todos, and write to them with setTodos()

addTodo does the actual work of saving it to the database (via our REST API) then creates a new todos array by adding our new one to the end. But we need to pass this down into our AddTodoForm. Here’s the main part of the App that returns out HTML, in this case that’s the list of todos and our form:

 return ( <main> <h1>To do</h1> <TodoList todos={todos} onDeleteTodo={deleteTodo}/> <AddTodoForm onAddTodo={addTodo} /> </main> )

You can see here that the todos array and a function deleteTodo() are passed into the the TodoList component, and that our addTodo() function is passed to the AddTodoForm.

In React, things like this that are passed into a component are passed as a single object variable called ‘props’ - short for properties. It seems crazy to me to be bundling them like this in a language in 2023 rather than passing them explicitly as separate variables. This lack or clarity about what’s being passed into a component is doubtless one of the reasons TypeScript is such a common combo with React. It’s certainly the first time I’ve felt the need of it.

There is a lighter partial solution to adding types to props so that the linter can call out any issues - this is the PropTypes library - once it’s installed, we import it with import PropTypes from 'prop-types'; then we can add a definition for the props at the bottom of the file. For our AddTodoForm, this would look like this:

AddTodoForm.propTypes = { onAddTodo: PropTypes.func.isRequired,};

Now the linter will prevent us from using anything other than props.onAddToDo, and it will flag if it’s being used as anything other than a function.

Anyway, the props are passed in and we can extract the function from it to use.

import { useState } from 'react';function AddTodoForm(props) { const [value, setValue] = useState(''); const handleSubmit = (event) => { event.preventDefault(); if (!value) return; props.onAddTodo({ todo_item: value }); setValue(''); }; return ( <form onSubmit={handleSubmit}> <input type="text" name="todo_item" id="todo" value={value} onChange={e => setValue(e.target.value)} required /> <button type="submit">Add</button> </form> );}export default AddTodoForm;

The arrangement of elements in this file will start to become familiar - there’s often some state at the top with the useState() hook, then a few handler functions, then our final return of the ‘HTML’.

Our TodoList is a bit simpler in that it doesn’t have any handlers, but a better illustration of using PropTypes since it has access to the global state of the todos.

import PropTypes from 'prop-types';function TodoList(props) { return ( <ul> {props.todos.map(todo => ( <li key={todo.id}> {todo.todo_item} <button onClick={() => props.onDeleteTodo(todo.id)}> Done </button> </li> ))} </ul> )}TodoList.propTypes = { todos: PropTypes.array.isRequired, onDeleteTodo: PropTypes.func.isRequired};export default TodoList;

Conclusion

You would not sensibly reach for React for a project this size - the complexity of the tooling, and the fact that we’re now shipping 150K of Javascript to do something we were nicely achieving in 2K of vanilla, or 15K with htmx makes me deeply uncomfortable. Nevertheless, hundreds of thousands of developers can’t be wrong - React’s component model is a powerful one for building modern single page applications, especially when it allows you to pull in components from public or corporate collections.

I plan on doing some more React - partly because its just such big part of the webdev world, and partly because I’d like to get some experience with TypeScript, so I’m fishing around for a medium size project to play with both of these technologies.

(source)

Openlayers & Vite

Thu, 26 Jan 2023 00:00:00 +0000

In Randy Pausch’s last lecture he talks about the benefit of brick walls in our lives - they tell us how much we really want something. Software development is full of these brick walls - things we want to do, but there’s a barrier to achieving it. Will we persevere and accomplish the thing, give up, or some other compromise.

In heroic tales, the protagonist overcomes all obstacles to achieve the goal. In life and especially in software development, that’s not always the smart thing to do - to stubbornly invest in an outcome, often disproportionately to the benefit. Here’s my brick walls from today.

I had made a web page showing text of the updated lat/long of the ISS. It met the requirements, but was not very exciting. The obvious thing to do with this information would be to show it on a map.

Moving map

Obviously there are lots of options for this, none of them were as simple as I would have liked, and I wanted a free one. OpenLayers sounded like it would do the job, and the download to showing a map in the demo app time was about five minutes - we’re off to a good start.

Wall 1 - complicated library

I’m not joking when I say OpenLayers is comprehensive. It appears to do everything you could possibly want. The flipside of this is complexity. I managed to get the map scrolling so the ISS position was the centre of the map, and discovered how to add a dot as a feature to represent the ISS, but then when I wanted to get that dot to move I was increasingly out of my depth.

Of course, there’s nothing magical here - it’s a gigantic, well documented API, and there’s a smattering on answers on StackOverflow. I’m smart enough to get my head around it, find some repos using it and dissect them and so on. The question is one of cost/benefit. I’m essentially building a toy for my own amusement - would the time be better spent on moving on to the next part of my course?

Wall 2 - overlapping images

I have a better idea anyway - since the ISS should be at the centre of the map, I can just stick a picture of the ISS there. I assume this is possible with CSS?

This turns out to be a low wall. The CSS for my image is:

img {
 position: absolute;
 top: 50%;
 left: 50%;
}

The container (that holds the map and this image of the ISS) has position:relative this all works on the first try, and my ISS png is positioned perfectly in the centre of the map at it’s correct location, and it changes correctly as the window is resized.

Wall 3 - Vite

The process of creating the demo app from the Getting Started instructions for OpenLayers involves something called Vite. Apparently it’s a “Next Gen Frontend Tooling” which does not really tell me much. I’ve heard it mentioned in passing a couple of times, and know it’s pronounced veet. A bit like when I was using React, there’s a node build step that fills a directory with the distributed files - I’m guessing this is something to do with pulling in just the parts of the giant library I’m using - but there’s 260K of JavaScript and a 1.6MB .map in there, so I feel some handcrafting or a CDN should be involved.

If the .map file is in fact the map, that’s actually pretty amazing for a map of the entire world that I can zoom down to individual street level - so it’s probably not, but either way it’s massive overkill for what this application needs. All I really need for this is a 1000x500 px image of a map of the world. Still here we are.

So I don’t really understand Vite, but I can follow the instructions enough to get the live server running for development, and to build the distribution files.

Wall 4 - GitHub Pages

I love GitHub pages, and have a couple of apps up on it here and here. It works by specifying a branch (which can include main) in the repo to expose, or by starting a repo with your GitHub username - for example, mine would be iankulin.github.io

I had my original (non-map) version of the iss location working on Pages as a subdirectory of the main iankulin page. For the map version, I publish it directly from the docs directory of the main branch of it’s own repo. About this time, I realised that my original version was mysteriously not working. I would have been okay with that, but neither was the new version, which as usual ‘wOrKEd On mY mAChiNe’.

I can see now what the problem was with my original version. I had copied the source files of the non-map version to the /iss folder of my main github.io page, so it’s address had been https://iankulin.github.io/iss/. Meanwhile, I’d named the new map-version repo ‘iss’ and published it from that repo - so its link was, you guessed it https://iankulin.github.io/iss/ After a bit of shuffling around, the old one is now working correctly at https://iankulin.github.io/cwd/iss/

Wall 5 - Vite again?

Meanwhile, the new version, with the moving map was clearly loading the HTML, but no sign of the ISS image, the .css or .js

I’m in unfamiliar territory here with Vite, but since I started with the bundled my-app app, I’m sort of expecting everything to just work, unless it’s something to do this the GitHub Pages hosting. I do go down a rabbit hole about how they are designed for Jekyll. But a simpler explanation might be the links to those resources in the HTML. They all had a forward slash in front of them, like

/assets/iss.d6272ccf.png

where as I would have been expecting

assets/iss.d6272ccf.png or even ./assets/iss.d6272ccf.png

(a side note - I have no idea why *ix systems use ./ to mean the current directory. It would be like prefixing everyone’s name with parent’s child when you’re talking to them).

So anyway, I just started manually editing the built code which doesn’t seem like great practice:

It didn’t immediately solve my problem, but I’m not sure what the update rate for Pages is, and when I looked the next morning, it was working.

Wall 6 - The last 90%

Tom Cargill (Bell Labs in the 80’s) is credited with noticing that the first 90% of the code accounts for the first 90% of the development time and the remaining 10% accounts for the remaining 90%. It certainly feels right that solving the problems and getting the MVP/prototype up and working - aka the fun bit, is not even the half way point in a project.

Even in this very simple app, with the shortcuts I’ve made, there’s still significant work to do:

I need to disable the user’s ability to scroll around the map - since it breaks the illusion that the ISS picture is map of the map (or correctly render it as a map layer).
There needs to be a delay or something so the first render of the map is based on a fetched ISS position.
It ISS picture is not quite in the centre - it’s not noticeable on a laptop, but on mobile it’s very evident.
Actually, the whole mobile experience needs a bit of work. That lat/long display does not fit as written. Better to pop the elements into a grid so we can stack them when the screen gets narrow.

Will I do these things? Is the trip worth the gas? I need to balance progressing in the course with the things I can learn by finishing everything off carefully. In this case, since I’m way, way past what the course exercise was, I’ll leave it as is. Eventually I’ll work back through my GitHub with a recruiter’s eye, and things like this will need fixed to production standards or made private.