❤
npm
Sign UpSign In

qompile

1.1.1 • Public • Published

Qompile

Build with Container Queries. Ship CSS.

This tool converts Container Queries to CSS Media Queries by consuming an HTML input file and a CSS stylesheet.

Included in this compiler is a mixin for container queries, named containerQuery() which accepts three arguments: selector, test, and stylesheet:

  • selector is a CSS selector list quoted as a string
  • test is a JavaScript function that accepts a DOM node and returns true/false
  • stylesheet is a CSS stylesheet quoted as a string, anywhere the selector :self is used it will be replaced with a selector targeting the matching element

To write a container query applying a green background to a <div> element when it is wider than 500px you could write a query in this format:

${containerQuery('div', el => el.offsetWidth > 500, `
  :self {
    background: lime;
  }
`)}

What does it do?

This plugin is capable of prerendering width-based container queries, as long as the width of the elements wit breakpoints is ultimately derived from the width of the viewport in the layout.

It is also possible to use a very limited set of element queries (like setting a style based on things present in your HTML) that are non-interactive and as long as they won't need updating after the page loads. Watch for more demos exploring what can be predicted in advance!

What does it not do?

It does not support any height-based container queries, nor any width-based container queries on element in layouts that change in ways not deriving from width of the viewport.

For example, if you have a collapsing sidebar that can be toggled without the viewport changing width, qompile wouldn't be able to predict the widths of elements in both states.

It is also impossible to predict elements that have been added to the page after the page has loaded.

If you're looking for realtime element & container queries that are able to adapt to new elements and events in the browser, check out a CSS reprocessor like EQCSS, CSSplus, reproCSS, JS-in-CSS, or QSS.

Usage

Install Qompile from npm

npm -i qompile

HTML Compiler

The simplest usage of Qompile on the command line outputs a test HTML and CSS to the console:

qompile

A normal usage where you are consuming a file named input.html and a stylesheet named styles.css and outputting them as a file named output.html might look like this:

qompile input.html -c styles.css -o output.html

Options

If you want to fine-tune the output more, here is a list of all supported options and a description of what they are used for:

qompile [-h|--html]* input.html [-c|-css] styles.css [-r|--range] 100:2000 [-s|--step] 100 [-o|--output] output.html [-e|--external] external.css [-v|--verbose]
-h | --html

The path name of the HTML file to be read

-c | --css

The path name of the stylesheet file to be read

-r | --range

A colon-separated pair of numbers setting the minimum and maximum widths. Default range is 1:2000

-s | --step

A number defining the step size between snapshots. Default step is 100

-o | --output

The path name of the HTML file to output

-e | --external

The path name of the external CSS file to output

-v | --verbose

Enables logging of the result to the console

-m | --minify

Enables rule de-duplication via CSSnano, and media query consolidation via css-mqpacker

--help

Dislpays help text

Live Debugging

This compiler comes with a companion JavaScript runtime for debugging and previewing purposes. If you want to preview what the result of adding a 'Qompile' stylesheet to an HTML document will look like, include a link to the preqompile.js file in your HTML document like this:

<script src=preqompile.js></script>

For a comparison between live container queries using preqompile and container queries flattened to CSS media queries using qompile, check out the following demos:

Examples

Widget Demo

Nested Components Demo

Calendar Demo

Element Queries Demo

Dependents (0)

Package Sidebar

Install

npm i qompile

Weekly Downloads

2

Version

1.1.1

License

MIT

Last publish

Collaborators

  • tomhodgins
Try on RunKit
Report malware