Try It Yourself
The whole point of Single Source is that anyone, regardless of their technical experience, can use it! To make changes to your very own hackathon live site powered by Single Source:
- Clone the repo at https://github.com/andrewdimmer/single-source
- Read the documentation at https://github.com/andrewdimmer/single-source/blob/main/docs/dataStructure.md
- Edit any of the .json files in the
- In a terminal, go to the
websitefolder, and run the command
npm run start
- You can see the changes you have made in your browser (it should pull up automatically, but if it doesn't the default link is localhost:3000)
- Click the debug icon in the lower right-hand corner of the screen to see the logs from the parser.
- Repeat steps 2 and 3 as many times as you want. Your site will automatically refresh with the new changes.
- To stop the server, press
Ctrl + Cin the terminal.
Many hackathon teams have diverse roles with different skill sets, which is great in the sense that people become an expert in a single area. However, this makes the technical development of things like the live site a bottleneck, as not every team has people with technical skills, but every team needs the technical development team to make updates to the website based on what they are doing. Single Source is designed to be a no-code-required live site template for hackathon organizers to provide a single source of information to hackers at virtual hackathons. This means that anyone on the organizing team can update the live site based on the knowledge their team has without any programming experience, but it is still customizable if the technical team wants to change the source code.
What it does
Single Source provides a no-code-required solution to creating hackathon live sites. To do this, anyone (regardless of technical experience) can read the documentation to see what data to put where, then add any data that they or their team knows (example: when a tech talk is). Next, they just need to run the command
npm run start, and it will automatically generate a local preview for the organizer to see. A parser goes through and centralizes all of the data and it is rendered into their browser at localhost. From there, they can enter debug mode while on localhost, and see if the parser had any recommendations to improve the data quality or fix errors. Once they're satisfied with the data, all that a tech team member needs to do is run the deploy script (say, to GitHub pages or Firebase), and the update is live on the site.
The live site currently supports displaying information about:
- General hackathon information
- The "Stage" of the hackathon (time until hacking starts, time until hacking ends, time until judging, etc.)
- Events and Activities happening at the hackathon
- Prizes and Eligibility
- Important Links (Discord, Twitch, Devpost, etc.)
- Hacker Resources (GitHub Student Developer Pack, etc.)
It is also worth noting that unlike most live sites, Single Source can automatically reset the timer and count down until the next part of the hackathon with no human intervention.
Single Source also displays all events in your local time zone, so you don't need to guess on the time zone conversions (either as an organizer to convert it, or as a hacker to attend events).
How I built it
To make sure that the live site was responsive across all devices, I built it in React with Typescript, and styled it using Material UI. From there, I made sure that there was separation between the data and the UI by adding a parsing layer, so one could change without accidentally breaking the other. This is key, as the parser literally prevents anyone from breaking the site unless they physically delete code files, so one mistake doesn't bring down the site.
Challenges I ran into
There was a lot of data validation to accomplish, and it was difficult trying to design everything to be extensible to allow any data while the type checker was on and telling me exactly what the data I had was. After some troubleshooting, I figured out that I could manually set all the data types to "any" as they came into the parser, which provided the level of abstraction I needed to separate the data and the UI, and to add in all the data validation to handle every case.
Accomplishments that I'm proud of
I got the whole framework up and running for a minimal viable product. I'd like to go through and add more features (like filtering events), and some more data (like mentor profiles to show what they can help with, and sponsor logos), but in terms of a proof of concept I got everything to the point where I could use this for a hackathon as it is, which is a really cool feeling.
What I learned
I learned a ton about data validation, and how to think through different ways to parse the input to get a standard output. This was especially important for figuring out how to read a time zone offset in as a string, and convert it to the numbers of hours off UTC.
What's next for Single Source
I'd like to add in more features like filter events by type and automatically hiding ones that have passed. I'd also like to add some more data as mentioned above. Finally, I'd like to open source the project so any organizing team can fork the repo and use it.