Interactive Pkl Primer - Learn Pkl in Your Browser

[browdues]

Hi everyone,

We just launched something we're pretty excited about: https://pkl.platform.engineering

It's an interactive Pkl tutorial that runs entirely in your browser: 16 steps covering basic values through templates, constraints, and custom validation. Live code editing with instant output in whatever format you need (JSON, YAML, XML, you name it).

No installation, no setup, just start typing and see what happens.

After building the CodeMirror language package for Pkl, we wanted to create a playground where people could actually use it. This is way more fun than reading docs 😄

GitHub: https://github.com/platform-engineering-labs/pkl-primer

We'd love feedback: Ideas for topics we should cover? Something confusing? Drop an issue in the repo.

Happy configuring!

[bioball]

Hey, awesome work! This looks really great, and a much nicer format than our current tutorial.

I think there's currently a bug, because clicking "Render" gives me this error:

Invalid code

Environment variable access not allowed

By the way, some notes for you as I was going through this:

• Idiomatic Pkl code is typically separated into a template module, and downstream modules that amend the template. It might be good to introduce these earlier on, because of how prevalent and important they are when you write Pkl code.

  • The base template defines schema, and also can contain abstractions.
  • A "template" is not a technical term in Pkl, just the name of this design pattern.
  • We talk about "templates" in our tutorial

• A module that doesn't amend anything itself is also a class. This code defines a top-level class called Foo with one class method and one class property:

  module Foo
  
  baz: String
  
  function getBar(qux: Int): Boolean = /* etc */

• It's actually somewhat of an anti-pattern to define a property whose type is an Object, with default values. For example, this code:

  module Acme
  
  foo: Listing<Int> = new { 1; 2; 3 }

  This is because of how the new keyword works; it amends the default value.
  In this case, the default value is new Listing { 1; 3; 4 }.
  So, if you later write this:

  amends "Acme.pkl"
  
  foo = new { 2, 3, 4 }

  This looks like you are defining a new listing, but you are actually adding elements to the existing listing!
  The way you avoid this is to:

  1. Don't define default values for input properties (this excludes local, fixed, and const properties)

  2. For shared base values, create a shared base instance instead. For example:

     // base.pkl
     amends "Acme.pkl"
     
     foo = new { 1; 2; 3 }

• Not sure how doable this is, but, often you model "amending" through module amends (e.g. my module starts with amends "../some/path.pkl"). Instead of creating objects inline in a single module, the object is the whole module. It'd be cool to show this, but might be hard in a single web editor format.

[browdues]

Hey! Thanks so much for the thorough review - really appreciate you taking the time!

Love all these suggestions and implementing them now. The single file editor makes the module-level amends pattern a bit trickier to demonstrate, but I'll make sure it gets covered. I'm thinking a combination of explanation in the content + a code example.

Thanks again for the detailed feedback!