Skip to main content

jan 04, 2025

🔗 Vanilla project starter template

It's quite a common experience for front-end developers go picking up a project that's not been touched for a while and find it hard to get a development environment running in a few minutes.

What usually happens is that the project is using a framework or a build tool that's not been updated in a while. Usually it's also becoming more experienced with the years that makes us realize that we have made the wrong choices or haven't been following best practices, for code reusability and maintainability when the project was originally created.

This project aims to provide a simple starter project using vanilla javascript, few dependencies as possible and following some sensible good practices.

# No frameworks

Nowadays frameworks are a must for any project, and full-featured frameworks like React are not the only option, for example AlpineJS is perfect for adding just few interactive components. But for this project the aim is not to use any framework by default, just plain vanilla javascript, and for the few components that need to be interactive, Web Components will be used, they do not provide the best developer experience, but they are the most future-proof way to create reusable components, and can be ported to any project without any issues.

# No build tools

This starter template doesn't come with a predefined build tool, all assets and dependencies are linked into index.html directly, leveraging native ES modules imports and web components. Each component or functionality is a separate file that can be imported if needed or commented out if not. All external dependencies are included from CDN links.

<!-- Main CSS -->
  <link href="css/main.css" rel="stylesheet">
  <!-- Utils CSS -->
  <link href="css/utils.css" rel="stylesheet">
  <!-- Prism CSS -->
  <link href="css/prism-one-dark.css" rel="stylesheet">
  <!-- Code sandbox CSS -->
  <link href="css/code-sandbox.css" rel="stylesheet">
  <!-- Markdown CSS -->
  <link href="css/markdown.css" rel="stylesheet">
  <!-- Tailwind CDN Script -->
  <script src="https://cdn.tailwindcss.com"></script>
  <!-- State management -->
  <script type="module" src="js/state.js"></script>
  <!-- Components -->
  <script type="module" src="js/prism.js"></script>
  <script type="module" src="js/md-block.js"></script>
  <script type="module" src="js/tweakpane.js"></script>
  <script type="module" src="js/code-sandbox.js"></script>
  <script type="module" src="js/counter-display.js"></script>
  <script type="module" src="js/counter-button.js"></script>

However, if you need to use build tools, add npm-installed dependencies, add hot-reloading, etc, Vite is the recommended build tool, and I've added a light guide on how to set it up in the README.md.

  1. Install Vite
npm install -D vite
  1. Run Vite
npx vite

# Reusable components

This starter template is not meant to be the starting point for a production-ready, feature-rich web application, but rather a playground to test out new ideas, or to create small web-based projects, without having to worry about maintaining dependencies and frameworks on the long run.

Not counting the web-components added for testing, there are only two imported components that I found sensible including, given the scope of the template:

  • leaverou/md-block, to include and render any markdown file in the page at runtime, like the README.md or a blog post draft.
<md-block src="README.md"></md-block>
  • a code-sandbox web component, for displaying an interactive code sandbox for HTML, CSS and javascript, similar to what CodePen does. I'm using a fork of Chris Ferdinandi'scode-sandbox web component, with a few added features.
<code-sandbox>
	<textarea for="html"></textarea>
	<textarea for="css"></textarea>
	<textarea for="js" open src="/assets/demo.js"></textarea>
</code-sandbox>

The great thing about web-components is that after all it's just client-side javascript, with the unexpected benefit that if the rendered markdown text contains a web component outside of a code block, it will be rendered as a web component, and not as a string. No need for MDX.

# demo.md

This counter button **works!** 

<counter-button></counter-button>

# Dependencies

  • cocopon/tweakpane for interactive controls. This is optional but plugged with state.js, which fires events on value changes to update the UI and store values to local storage.
  • PrismJS for syntax highlighting both in the code sandbox and in the markdown files.
  • Tailwind Play CDN for quick styling and utility classes.

# Repository

# Resources