Skip to content

Commit

Permalink
feat: Use @eik/common to load config in a project (#84)
Browse files Browse the repository at this point in the history 
* feat: Use @eik/common to load config in a project

* feat: Use logic in @eik/common to load config from eik.json or package.json

BREAKING CHANGE: Use logic in @eik/common to load config from eik.json or package.json

* chore: Adjust for PR comments

* chore: Remove extra whitespace

Co-authored-by: Trygve Lie <trygve.lie@finn.no>
  • Loading branch information
@trygve-lie
trygve-lie and Trygve Lie committed Mar 2, 2021
1 parent 71916df commit 371dcda
Show file tree
Hide file tree
Showing 6 changed files with 317 additions and 241 deletions.
189 changes: 110 additions & 79 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,7 @@
# postcss-import-map
# @eik/postcss-plugin

PostCSS [Eik](https://eik.dev/) plugin to support the use of import maps to map "bare" import specifiers in CSS @import rules.

**Notes:**

- **This plugin should probably be used as the first plugin of your list.**
- **If you use `postcss-import` please [read this.](#postcss-import-usage)**

## Installation

```bash
Expand All @@ -16,36 +11,36 @@ $ npm install @eik/postcss-plugin
## Usage

```js
// dependencies
var fs = require('fs');
var postcss = require('postcss');
var plugin = require('@eik/postcss-plugin');
const postcss = require('postcss');
const plugin = require('@eik/postcss-plugin');
const fs = require('fs');

// css to be processed
var css = fs.readFileSync('css/input.css', 'utf8');
// CSS to be processed
const css = fs.readFileSync('css/input.css', 'utf8');

// process css
postcss()
.use(
plugin({
imports: {
'normalize.css':
'https://unpkg.com/normalize.css@8/normalize.css',
},
})
plugin()
)
.process(css, {
// `from` option is needed here
from: 'css/input.css',
})
.then(function (result) {
var output = result.css;

console.log(output);
console.log(result.css);
});
```

`css/input.css`:
## Description

This plugin transforms "bare" import specifiers to absolute URL specifiers in
CSS modules by applying an Import Map ahead of time.

For a more detailed description of Import Maps, please see our [Import Maps section](https://eik.dev/docs/mapping_import_map).

The main target for Import Maps is to map import statements in EcmaScript Modules but it can be applied to CSS import statements too.

Given the following CSS:

```css
@import 'normalize.css';
Expand All @@ -55,92 +50,128 @@ body {
}
```

will give you:
when applaying the following Import Map:

```json
{
"imports": {
"normalize.css": "https://cdn.eik.dev/normalize.css@8/normalize.css",
},
}
```

one will get a transformed CSS like so:

```css
@import 'https://unpkg.com/normalize.css@8/normalize.css';
@import 'https://cdn.eik.dev/normalize.css@8/normalize.css';

body {
background: black;
}
```

## PostCSS Import Usage
## Options

If you're using [postcss-import](https://github.com/postcss/postcss-import) make sure you update the `plugins` option.
`postcss.config.js`
This plugin takes the following as options:

| option | default | type | required | details |
| ------- | --------------- | -------- | -------- | ----------------------------------------------------------------------------- |
| path | `process.cwd()` | `string` | `false` | Path to directory containing a eik.json file or package.json with eik config. |
| urls | `[]` | `array` | `false` | Array of import map URLs to fetch from. |
| maps | `[]` | `array` | `false` | Array of import map as objects. |

The plugin will attempt to read import map URLs from [`eik.json` or `package.json`](https://eik.dev/docs/overview_eik_json) files in the root of the current working directory if present.

```js
module.exports = (ctx) => ({
plugins: [
require('@eik/postcss-plugin')(),
require('postcss-import')({
// It needs to be added here as well to ensure everything is mapped
plugins: [require('@eik/postcss-plugin')],
}),
],
});
postcss()
.use(
plugin()
)
.process(css, {...})
.then(...);
```

## Reading config from eik.json or package.json
The path to the location of an `eik.json` file can be specified with the `path` option.

By default, this plugin will try to read config from your projects `eik.json` or `package.json` files in the root of the current working directory.
```js
postcss()
.use(
plugin({ path: '/path/to/eik-json-folder' })
)
.process(css, {...})
.then(...);
```

The path to the location of an `eik.json` file can be specified with the `path` option.
`path` defaults to the current working directory.
The plugin can also be told which URLs to load import maps from directly using the `urls` option.

```js
module.exports = (ctx) => ({
plugins: [
require('@eik/postcss-plugin')({ path: '/path/to/eik.json' }),
require('postcss-import')({
// It needs to be added here as well to ensure everything is mapped
plugins: [
require('@eik/postcss-plugin')({
path: '/path/to/eik.json',
}),
],
}),
],
});
postcss()
.use(
plugin({ urls: 'http://myserver/import-map' })
)
.process(css, {...})
.then(...);
```

Additionally, individual mappings can be specified using the `maps` option.

```js
postcss()
.use(
plugin({
maps: [{
"imports": {
"normalize.css": "https://cdn.eik.dev/normalize.css@8/normalize.css",
},
}],
})
)
.process(css, {...})
.then(...);
```

### Precedence

If several of the options are used, `maps` takes precedence over `urls` which takes precedence over values loaded from an `eik.json` or `package.json` file.

ie. in the following example

```js
postcss()
.use(
plugin({
path: '/path/to/eik-json-folder',
urls: ['http://myserver/import-map'],
maps: [{
"imports": {
"normalize.css": "https://cdn.eik.dev/normalize.css@8/normalize.css",
},
}],
})
)
.process(css, {...})
.then(...);
```

The path to the location of a `package.json` file can be specified with the `packagePath` option.
`packagePath` defaults to the current working directory.
Any import map URLs in `eik.json` will be loaded first, then merged with (and overridden if necessary by) the result of fetching from `http://myserver/import-map` before finally being merged with (and overriden if necessary by) specific mappings defined in `maps`.

## PostCSS Import Usage

If you're using [postcss-import](https://github.com/postcss/postcss-import) make sure you update the `plugins` option.
`postcss.config.js`

```js
module.exports = (ctx) => ({
plugins: [
require('@eik/postcss-plugin')({
packagePath: '/path/to/package.json',
}),
require('@eik/postcss-plugin')(),
require('postcss-import')({
// It needs to be added here as well to ensure everything is mapped
plugins: [
require('@eik/postcss-plugin')({
packagePath: '/path/to/package.json',
}),
],
plugins: [require('@eik/postcss-plugin')],
}),
],
});
```

## Options

This plugin takes an [import map](https://github.com/WICG/import-maps) as options:

| option | default | type | required | details |
| ----------- | ------------------ | -------- | -------- | ----------------------------------------------------------- |
| path | `cwd/eik.json` | `string` | `false` | Path to eik.json file. |
| packagePath | `cwd/package.json` | `string` | `false` | Path to package.json file. |
| urls | `[]` | `array` | `false` | Array of import map URLs to fetch from. |
| imports | `{}` | `object` | `false` | Mapping between "bare" import specifiers and absolute URLs. |

This module only cares about "bare" import specifies which map to absolute
URLs in the import map. Any other import specifiers defined in the import map
are ignored.

## License

Copyright (c) 2020 Finn.no
Expand Down
15 changes: 5 additions & 10 deletions package.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,22 +2,17 @@
"name": "@eik/postcss-plugin",
"version": "3.0.0-next.1",
"description": "PostCSS plugin that uses Eik defined import map files to transform bare import specifiers to absolute URLs in @import rules",
"main": "dist/plugin.js",
"main": "src/plugin.js",
"files": [
"CHANGELOG.md",
"package.json",
"dist"
"src/"
],
"directories": {
"dist": "dist"
},
"scripts": {
"prepare": "npm run -s build",
"test": "tap test/*.js --no-coverage",
"test:snapshot": "TAP_SNAPSHOT=1 tap test/*.js --no-coverage",
"lint": "eslint .",
"lint:fix": "eslint . --fix",
"build": "rollup -c"
"lint:fix": "eslint . --fix"
},
"repository": {
"type": "git",
Expand Down Expand Up @@ -46,14 +41,14 @@
"eslint": "7.20.0",
"eslint-config-airbnb-base": "14.2.1",
"eslint-plugin-import": "2.22.1",
"eslint-config-prettier": "7.0.0",
"eslint-config-prettier": "8.0.0",
"fastify": "3.12.0",
"postcss": "8.2.6",
"rollup": "2.39.0",
"semantic-release": "17.3.9",
"tap": "14.11.0"
},
"dependencies": {
"@eik/common": "4.0.0-next.4",
"css-url-parser": "1.1.3",
"node-fetch": "2.6.1"
},
Expand Down
5 changes: 0 additions & 5 deletions rollup.config.js
View file

This file was deleted.

0 comments on commit 371dcda

Please sign in to comment.