Package aliases #118

New Issue

adam · 2025-12-30T01:21:06+01:00

adam commented

2025-12-30 01:21:06 +01:00

Originally created by @ericzbeard on GitHub (Mar 21, 2024).

It would be nice if we could alias package imports.

What I do now:

amends "package://github.com/aws-cloudformation/rain/releases/download/v1.8.2-alpha1/cloudformation@1.8.2-alpha1#/template.pkl"
import "package://github.com/aws-cloudformation/rain/releases/download/v1.8.2-alpha1/cloudformation@1.8.2-alpha1#/aws/s3/bucket.pkl"

Description = "testing imports"
Resources {
    ["Foo"] = new {
        Type = "AWS::S3::Bucket"
    }
    ["Bar"] = new bucket.Bucket {
        BucketName = "my-bucket-name"
    }
}

What I would like to do:

use "package://github.com/aws-cloudformation/rain/releases/download/v1.8.2-alpha1/cloudformation@1.8.2-alpha1" as cfn

amends "cfn/template.pkl"
import "cfn/aws/s3/bucket.pkl"

or

amends cfn.template
import cfn.aws.s3.bucket

...

Originally created by @ericzbeard on GitHub (Mar 21, 2024). It would be nice if we could alias package imports. What I do now: ```pkl amends "package://github.com/aws-cloudformation/rain/releases/download/v1.8.2-alpha1/cloudformation@1.8.2-alpha1#/template.pkl" import "package://github.com/aws-cloudformation/rain/releases/download/v1.8.2-alpha1/cloudformation@1.8.2-alpha1#/aws/s3/bucket.pkl" Description = "testing imports" Resources { ["Foo"] = new { Type = "AWS::S3::Bucket" } ["Bar"] = new bucket.Bucket { BucketName = "my-bucket-name" } } ``` What I would like to do: ```pkl use "package://github.com/aws-cloudformation/rain/releases/download/v1.8.2-alpha1/cloudformation@1.8.2-alpha1" as cfn amends "cfn/template.pkl" import "cfn/aws/s3/bucket.pkl" or amends cfn.template import cfn.aws.s3.bucket ... ```

adam commented

2025-12-30 01:21:06 +01:00

@bioball commented on GitHub (Mar 21, 2024):

You can do this by declaring them as project dependencies. See docs here: https://pkl-lang.org/main/current/language-reference/index.html#project-dependencies

By the way: package URIs should only have the version once in their path, after the last @. This is because Pkl uses the base path to determine what the name of the package is. It then uses the package name to resolve dependencies.

If you are publishing packages as GitHub releases, a path you can take is:

Create a tag and release called <name>@<version> to hold the package assets
Use package://pkg.pkl-lang.org/github.com/<org>/<repo>/<name>@<version> as the package URI. This is a redirect server that redirects back to github.com.

For example, here's how we manage the releases for pkl-go: https://github.com/apple/pkl-go/releases. We create two GitHub releases for every release; one as the Go release, and one as the Pkl package release.

@bioball commented on GitHub (Mar 21, 2024): You can do this by declaring them as project dependencies. See docs here: https://pkl-lang.org/main/current/language-reference/index.html#project-dependencies By the way: package URIs should only have the version _once_ in their path, after the last `@`. This is because Pkl uses the base path to determine what the name of the package is. It then uses the package name to [resolve dependencies](https://pkl-lang.org/main/current/language-reference/index.html#resolving-dependencies). If you are publishing packages as GitHub releases, a path you can take is: 1. Create a tag and release called `<name>@<version>` to hold the package assets 2. Use `package://pkg.pkl-lang.org/github.com/<org>/<repo>/<name>@<version>` as the package URI. This is a redirect server that redirects back to github.com. For example, here's how we manage the releases for pkl-go: https://github.com/apple/pkl-go/releases. We create two GitHub releases for every release; one as the Go release, and one as the Pkl package release.

adam commented

2025-12-30 01:21:09 +01:00

@ericzbeard commented on GitHub (Mar 21, 2024):

I struggled with figuring out the right format for the PklProject file. I think I'm complicating the issue by releasing this package as a part of a larger repo, so it's not the only thing being released. See the assets in this release. Maybe it would be better to put this in a repo by itself, but it makes development a bit easier having it all together.

@ericzbeard commented on GitHub (Mar 21, 2024): I struggled with figuring out the right format for the [PklProject](https://github.com/aws-cloudformation/rain/blob/main/pkl/PklProject-template) file. I think I'm complicating the issue by releasing this package as a part of a larger repo, so it's not the only thing being released. See the assets in [this release](https://github.com/aws-cloudformation/rain/releases/tag/v1.8.2-alpha1). Maybe it would be better to put this in a repo by itself, but it makes development a bit easier having it all together.

adam commented

2025-12-30 01:21:09 +01:00

@ericzbeard commented on GitHub (Mar 21, 2024):

And thank you, the code is much cleaner now!

amends "@cfn/template.pkl"
import "@cfn/aws/s3/bucket.pkl"

Description = "testing imports"
Resources {
    ["Foo"] = new {
        Type = "AWS::S3::Bucket"
    }
    ["Bar"] = new bucket.Bucket {
        BucketName = "my-bucket-name"
    }
}

@ericzbeard commented on GitHub (Mar 21, 2024): And thank you, the code is much cleaner now! ```pkl amends "@cfn/template.pkl" import "@cfn/aws/s3/bucket.pkl" Description = "testing imports" Resources { ["Foo"] = new { Type = "AWS::S3::Bucket" } ["Bar"] = new bucket.Bucket { BucketName = "my-bucket-name" } } ```

adam commented

2025-12-30 01:21:10 +01:00

@bioball commented on GitHub (Mar 22, 2024):

Something else you can do here is to deploy these assets elsewhere, e.g. to an S3 bucket (and then maybe CNAME'd so the url is shorter). Pkl doesn't actually care where these packages come from, only that they are accessible via HTTPS.

Some notes about the PklProject:

you can define the version in an external file if you'd like, and read it in. This lets you avoid doing some string replacing before you do your packaging.
to help Pkl with stack traces, it's nice to provide sourceCode and sourceCodeUrlScheme.
Typically, the package's name should be the last segment of the base uri.

amends "pkl:Project"

package {
  name = "cloudformation"
  baseUri = "package://example.com/\(name)"
  version = read("path/to/some/version.txt").text.trim()
  packageZipUrl = "https://github.com/aws-cloudformation/rain/releases/download/v\(version)/cloudformation@\(version).zip"
  sourceCode = "https://github.com/aws-cloudformation/rain"
  sourceCodeUrlScheme = "\(sourceCode)/blob/v\(version)/pkl%{path}#L%{line}-%{endLine}"
}

@bioball commented on GitHub (Mar 22, 2024): Something else you can do here is to deploy these assets elsewhere, e.g. to an S3 bucket (and then maybe CNAME'd so the url is shorter). Pkl doesn't actually care where these packages come from, only that they are accessible via HTTPS. Some notes about the `PklProject`: * you can define the version in an external file if you'd like, and `read` it in. This lets you avoid doing some string replacing before you do your packaging. * to help Pkl with stack traces, it's nice to provide `sourceCode` and `sourceCodeUrlScheme`. * Typically, the package's `name` should be the last segment of the base uri. ```ts amends "pkl:Project" package { name = "cloudformation" baseUri = "package://example.com/\(name)" version = read("path/to/some/version.txt").text.trim() packageZipUrl = "https://github.com/aws-cloudformation/rain/releases/download/v\(version)/cloudformation@\(version).zip" sourceCode = "https://github.com/aws-cloudformation/rain" sourceCodeUrlScheme = "\(sourceCode)/blob/v\(version)/pkl%{path}#L%{line}-%{endLine}" } ```

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/pkl#118