npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

html-in-js

v1.5.2

Published

Easily write modular and flexible HTML sites using just the javascript you know and love

Downloads

30

Readme

HTML - in - JS

The Perfect Site Generator

Programming a simple, static, website is trickier than it looks. The first version is usually quick and easy to write but every subsequent version gets harder and more brittle with each change.

The lessons we have learnt in programming - localise scope, reuse components, calculate values from data - all hit a brick wall when coding a raw websites.

The problem is that HTML/CSS is not a 'real' programming language and it is a struggle to get it to behave properly. In response to this problem the programming community quickly moved on from using raw HTML/CSS and created new ways of generating them instead.

We call these 'templates' and the way most of them work is to create a new language structure that is some mix of HTML and supporting programming structures - loops, conditionals and so on.

Now these have been excellent solutions and have taken us far yet they all still suffer from two fundamental problems:

  1. They are not 'real' programming languages and hence always lag behind in implementing the full power available to a 'proper' language.
    • For example, how would you include some package that you found that does really nice Tree-shaking?
    • Or embed a new syntax highlighter someone has made?
    • Or color the background of a card based on the sentiment of the text in it?
  2. Developers need to learn this new language and so get the worst of both worlds
    • We need to learn a new language and all the little tricks it needs in order to get something non-standard done (hours of googling)
    • And what we’ve learned lacks much of the true power of any 'real' language like Javascript that we could have leaned instead.

So The Perfect Site Generator would - ideally - require

  1. No new language or concepts to be learnt
  2. Allow us to add to HTML/CSS loops, conditionals, functions, scoping - all the good stuff that we've discovered we like over these years.

And - with the advent of ES6 - this Magical Perfect Site Generation Option is now a reality!

icon

Just Use Javascript

In ES6 Javascript now provides Template Strings as part of it’s core language. While it is easy to overlook this addition to the language as a “just prettier syntax” Template Strings are pretty powerful things.

What is a template string? Well they are like ‘normal’ javascript strings except that they can contain placeholders. These are indicated by the dollar sign and curly braces (${expression}). So we can change this string:

'hello there ' + name + '! Great to see you.'

to this

`hello there ${name}! Great to see you.`

The power here comes when we realize that the expression is fully functional Javascript. That means we can call functions, include packages, do calculations, … - do everything we could do with the full power of Javascript behind us.

The best way to explain it's power is to provide examples and how-to’s so let’s do that next.

HTML - in - JS for Dummies

(or a quick look at some examples)

1. Use a simple HTML template

let index = `<!doctype html>
<html>
<head>
  <title>${title}</title>
</head>
<body>
  ${content()}
</body>
</html>`
write('index.html', index)

...

let title = 'Welcome to HTML - in - JS'

...

function content() {
  return `
<div class=container>
  <div class='col col-4'
    ${sidebar()}
  </div>
  <div class='col col-8'>
    ${maincontent()}
  </div>
</div>`
}
...

We can see how similar the content above looks like a “template language” but it’s just plain vanilla Javascript.

2. Use Markdown

We all love markdown. It’s a wonderful way of writing text with just enough symbols thrown in to make it pleasing to write and useful to generate.

So how would we use markdown if we wanted in our site? Simple, just write our content in markdown in some file

# First Fig
My candle burns at both ends;
It will not last the night;
But ah, my foes, and oh, my friends --
It gives a lovely light!
*-- Edna St Vincent Millay*

Then use our favorite markdown package to parse it and give us the content we need:

function poem(file) {
  return md.render(read(file))
}

3. Loop over table data

This is a classic use case for templates - looping. But now, instead of having to learn a new syntax we use javascript directly.

`<ul>
  ${data.map(item => `<li>${item}</li>`).join('')}
</ul>`

Helper Functions

When generating HTML-from-JS there are a few operations that are commonly required - reading from disk, saving a file, parsing markdown, using a HTML template, and so on.

Here we have some helper functions that support these common cases which can be used to quickstart your site development (or just as a starting point for anyone who is creating their own).

/*  example use */
const helper = require('html-in-js')

function createSite() {
  helper.save(helper.md(helper.read('content.md)), 'index.html')
  ...
}

This is the list of helper functions available:

Example Site

You can see an example of HTML-in-JS in action here

Your Contribution Welcome

The preceeding examples should have given you a feel for how simple and elegant it is to use HTML-in-JS.

I encourage anyone who believes in html-in-js to contribute more examples and how-to’s to spur ideas and drive html-in-js's adoption.

Thanks.