Skip to content

Commit

Permalink
rewriting importmap to support css files.
Browse files Browse the repository at this point in the history
  • Loading branch information
@donseba
donseba committed Mar 24, 2024
1 parent 341ff49 commit fd52c17
Show file tree
Hide file tree
Showing 8 changed files with 608 additions and 436 deletions.
249 changes: 152 additions & 97 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,139 +1,194 @@
# go-importmap

Golang importmap generator and super lightweight javascript library and asset manager.
ImportMap is a powerful Go package designed to simplify the management of JavaScript library dependencies for modern web applications. It facilitates the fetching, caching, and generation of import maps, allowing for seamless integration of JavaScript and CSS libraries directly into your projects. By abstracting the complexity of handling external library dependencies, ImportMap enables developers to focus on building feature-rich web applications without worrying about the underlying details of dependency management.
Features

In addition to generate the importmap section it can also cache external libraries and serve them from local storage.
- **Flexible Provider Interface**: Easily extendable to support different sources for fetching library packages, with a default implementation for cdnjs.
- **Automatic Caching**: Libraries are fetched and cached locally to improve load times and reduce external requests.
- **Import Map Generation**: Automatically generates import maps for included JavaScript and CSS files, adhering to the latest web standards.
- **Customizable Directories**: Configurable cache and assets directories to fit the structure of your project.
- **Shim Management**: Supports the inclusion of ES module shims for backward compatibility with non-module browsers.
- **Dynamic Package Management**: Add individual or multiple library packages with optional versioning and dependency requirements.

For now only cdnjs has been implemented because it provides a great api to interact with. There is a `Raw` client as well that mimics the process and returns the Raw field of the package struct.
## Getting Started
### Installation

## Example
To use ImportMap in your Go project, install it as a module:

```bash
go get github.com/donseba/go-importmap
```
### Usage Example

Here's a quick example to get you started with ImportMap:

```go
package main

import (
"context"
"fmt"
"log"
"context"
"fmt"
"log"
"log/slog"

"github.com/donseba/go-importmap"
"github.com/donseba/go-importmap/client/cdnjs"
"github.com/donseba/go-importmap/library"
"github.com/donseba/go-importmap"
"github.com/donseba/go-importmap/library"
)

func main() {
ctx := context.TODO()
pr := cdnjs.New()

im := importmap.New(pr)
im.SetUseAssets(true)

im.Packages = []library.Package{
{
Name: "htmx",
Version: "1.8.5",
},
{
Name: "htmx",
Version: "1.8.4",
As: "json-enc",
FileName: "ext/json-enc.min.js",
},
{
Name: "htmx-latest",
Version: "1.8.6",
Raw: "https://unpkg.com/browse/[email protected]/dist/htmx.min.js",
},
}

// retrieve all libraries
err := im.Fetch(ctx)
if err != nil {
log.Fatal(err)
return
}

// render the html block including script tags.
tmpl, err := im.Render()
if err != nil {
log.Fatal(err)
return
}

fmt.Println(tmpl)
ctx := context.TODO()

im := importmap.
NewDefaults().
WithLogger(slog.Default()).
ShimPath("https://ga.jspm.io/npm:[email protected]")

im.WithPackages([]library.Package{
{
Name: "htmx",
Version: "1.8.5", // locking a specific version
Require: []library.Include{
{
File: "htmx.min.js",
},
{
File: "/ext/json-enc.js",
As: "json-enc",
},
},
},
{
Name: "bootstrap",
Require: []library.Include{
{
File: "css/bootstrap.min.css",
As: "bootstrap",
},
{
File: "js/bootstrap.min.js",
As: "bootstrap",
},
},
},
})

// retrieve all libraries
err := im.Fetch(ctx)
if err != nil {
log.Fatal(err)
return
}

// render the html block including script tags.
tmpl, err := im.Render()
if err != nil {
log.Fatal(err)
return
}

fmt.Println(tmpl)
}
```

Result in the following with `SetUseAssets` set to `false`:

Resulting in the following output:
```html
<script async src="https://ga.jspm.io/npm:[email protected]/dist/es-module-shims.js"></script>
<link rel="stylesheet" href="/assets/css/bootstrap.min.css" as="bootstrap"/>
<script async src="https://ga.jspm.io/npm:[email protected]"></script>
<script type="importmap">
{
"imports": {
"htmx": "https://cdnjs.cloudflare.com/ajax/libs/htmx/1.8.5/htmx.min.js",
"htmx-latest": "https://unpkg.com/browse/[email protected]/dist/htmx.min.js",
"json-enc": "https://cdnjs.cloudflare.com/ajax/libs/htmx/1.8.4/ext/json-enc.min.js"
}
}
{
"bootstrap": "/assets/js/bootstrap.min.js",
"htmx": "/assets/htmx.min.js",
"json-enc": "/assets/ext/json-enc.js"
}
</script>
```
This above example initializes ImportMap with default settings and fetches the specified library packages from cdnjs.
It then generates an import map with the required JavaScript and CSS files, including the ES module shim
for compatibility with older browsers.

Result in the following with `SetUseAssets` set to `true`:
Finally, it renders the HTML block with the necessary script tags for the libraries.

```html
<script async src="https://ga.jspm.io/npm:[email protected]/dist/es-module-shims.js"></script>
<script type="importmap">
{
"imports": {
"htmx": "/assets/js/htmx/htmx.min.js",
"htmx-latest": "/assets/js/htmx-latest/htmx.min.js",
"json-enc": "/assets/js/htmx/ext/json-enc.min.js"
}
}
</script>
## Configuration

ImportMap offers several methods to customize its behavior according to your project's needs:

- **WithDefaults()**: Initializes ImportMap with default settings for cache and assets directories, and the ES module shim.
- **WithProvider(provider Provider)**: Sets a custom provider for fetching library files.
- **WithPackages(packages []library.Package)**: Sets multiple library packages to the import map.
- **WithPackage(package library.Package)**: Adds a single library package to the import map.
- **AssetsDir(dir string)**: Sets the directory path for assets, default is `assets`.
- **CacheDir(dir string)**: Sets the directory path for the cache, default is `.importmap`.
- **RootDir(dir string)**: Sets the directory paths for assets, cache, and root directories, respectively.
- **ShimPath(sp string)**: Sets the path to the ES module shim, default is `https://ga.jspm.io/npm:[email protected]/dist/es-module-shims.js`.

```

Output will look like the following:
## file structure

```
- .importmap
- bootstrap
- 5.1.3
- css
- bootstrap.css
- bootstrap.min.css
- bootstrap-grid.css
- bootstrap-grid.min.css
- js
- bootstrap.js
- bootstrap.bundle.js
- bootstrap.min.js
- htmx
- 1.8.4
- ext
- json-enc.min.js
- 1.8.5
- htmx.min.js
- htmx-latest
- 1.8.6
- htmx.min.js
- htmx.min.js
- ext
- json-enc.js
- ajax-header.js
- apline-morphd.js
- ... etc
- assets
- js
- bootstrap
-5.1.3
- css
- bootstrap.min.css
- js
- bootstrap.min.js
- htmx
- ext
- json-enc.min.js
- htmx.min.js
- htmx-latest
- htmx.min.js
- 1.8.5
- htmx.min.js
- ext
- json-enc.js
```

as you can see the `.importmap` contains the files per version and the assets are created without a version a version folder. This has been done by design so you don't have to update the snippet while doing an update.
As you can see the `.importmap` contains all the files fetched from the cdnjs, while the `assets` contains the files that are used in the importmap.

## Variations
## RAW Imports

it is possible to bypass the cdnjs by using the `Raw` param on the package.

```go
im.Packages = []library.Package{
{
Name: "htmx",
Raw: "https://some.url.to/repo/with.js",
},
}
im.WithPackages([]library.Package{
{
Name: "htmx",
Version: "1.8.6",
Require: []library.Include{
{
Raw: "https://unpkg.com/browse/[email protected]/dist/htmx.min.js",
As: "htmx",
},
},
},
})
```

This wil generate:
```json
{"imports":{"htmx":"https://some.url.to/repo/with.js"}}
```
{"imports":{"htmx":"https://unpkg.com/browse/[email protected]/dist/htmx.min.js"}}
```

## Contributing

Contributions are welcome!
Whether it's bug reports, feature requests, or code contributions,
please feel free to reach out or submit a pull request.
## License

Distributed under the MIT License. See `LICENSE` for more information.
49 changes: 22 additions & 27 deletions client/cdnjs/cdnjs.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,8 @@ import (
"encoding/json"
"errors"
"fmt"
"net/http"
"strings"

"github.com/donseba/go-importmap/library"
"net/http"
)

var (
Expand Down Expand Up @@ -44,59 +42,56 @@ func New() *Client {
}
}

func (c *Client) Package(ctx context.Context, p *library.Package) (string, error) {
url := defaultApiBaseURL + p.Name
func (c *Client) FetchPackageFiles(ctx context.Context, name, version string) (library.Files, string, error) {
url := defaultApiBaseURL + name

req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
if err != nil {
return "", err
return nil, "", err
}

resp, err := http.DefaultClient.Do(req)
if err != nil {
return "", err
return nil, "", err
}
defer resp.Body.Close()

if resp.StatusCode != http.StatusOK {
return "", errors.New(fmt.Sprintf("client api responded with code %d", resp.StatusCode))
return nil, "", errors.New(fmt.Sprintf("client api responded with code %d", resp.StatusCode))
}

var sr SearchResponse
err = json.NewDecoder(resp.Body).Decode(&sr)
if err != nil {
return "", err
return nil, "", err
}

var (
useVersion = sr.Version
useFilename = sr.Filename
path = sr.Latest
useVersion = sr.Version
)

if p.Version != "" && p.Version != useVersion {
if version != "" && version != useVersion {
for _, v := range sr.Versions {
if p.Version == v {
if version == v {
useVersion = v
break
}
}
}

if p.FileName != "" && p.FileName != useFilename {
for _, assets := range sr.Assets {
for _, v := range assets.Files {
if p.FileName == v {
useFilename = v
}
}
}
}
basePath := c.cdnBaseURL + name + "/" + useVersion + "/"

p.FileName = useFilename
var files library.Files

path = strings.Replace(path, sr.Version, useVersion, 1)
path = strings.Replace(path, sr.Filename, useFilename, 1)
for _, assets := range sr.Assets {
for _, v := range assets.Files {
files = append(files, library.File{
Type: library.ExtractFileType(v),
Path: basePath + v,
LocalPath: v,
})
}
}

return path, nil
return files, useVersion, nil
}
Loading

0 comments on commit fd52c17

Please sign in to comment.