Docsite rewrite

[wkillerud]

Written with three different readers in mind:

• application developers using Eik
• devs responsible for updating dependencies and import maps
• folks responsible for running and monitoring the server

Might be easier to review locally.

git pull
git checkout cli
npm install
npm run dev

Open http://localhost:3000/

[leftieFriele]

If you've run this project before, you'll need to remove node_modules in order to build it.

[leftieFriele]

❤️ I love this, it's a huge step forward in terms of inviting new users to the project.

I have three general comments:

• I have a couple of comments. When arriving on the frontpage and select one of the choices, I'm sent to a new page where the left hand navigation doesn't reflect that I selected "Runnig Eik server" or "Publishing to Eik". That made me wonder if I made the right choice.
• I think that "Why Eik" could be given less emphasis, as you're most likely arriving here because someone already told you to do so. One option could be to put it in the top navigation next to "Documentation".
• The last thing is the use of "shared dependencies" in places, as opposed to "package". I found it confusing as in my mind as a "shared dependency" isn't really saying much. Perhaps I didn't read what this means, but it felt a bit strange to read "shard dependency" and then have to think "oh right, a package" 😄

[leftieFriele]

Suggested change

	Now that you have [published a shared dependency](/docs/dependencies/npm/) to Eik and seen how to update it, it's time to set up an alias.
	Now that you have [published package](/docs/dependencies/npm/) to Eik and seen how to update it, it's time to set up an alias.

I think "shared dependency" is a bit alien, and we genereally use package elsewhere in the docs.

[wkillerud]

I think I wanted to distinguish "shared dependency"/npm from "application package"/pkg. But we can use "package" here, no worries.

[wkillerud]

Hmm, feels a bit clunky in places

Like how the npm package type is designed for shared packages, map is designed to hold your import maps.

versus

Like how the npm package type is designed for shared dependencies, map is designed to hold your import maps.

The "package" term is a bit loaded in Eik 😅

[leftieFriele]

yeah, it all get's a bit messy 😄 however I'm not sure using an unfamiliar term makes it easier, as it leaves the reader to figure out what is ment by it.

it might be ok to leaved it... as "shared packages" is kind of implicit in this context to it can end up like this:

Like how the npm package type is designed for npm packages, map is designed to hold your import maps.

[leftieFriele]

Suggested change

	Publishing shared dependencies and aliasing them helps nothing if application code doesn't use them. Import maps make it easier for developers to discover and use dependencies you publish to your Eik server.
	Publishing packages and aliasing them helps nothing if application code doesn't use them. Import maps make it easier for developers to discover and use packages you publish to your Eik server.

[leftieFriele]

Suggested change

	Like how the `npm` package type is designed for shared dependencies, `map` is designed to hold your import maps.
	Like how the `npm` package type is designed for sharing packages, `map` is designed to hold your import maps.

[leftieFriele]

Suggested change

	We encourage using aliases for import maps, similar to dependencies. That way an import map can be updated on Eik and new builds that use the import map get the updated map without changing their configuration.
	We encourage using aliases for import maps, similar to packages. That way an import map can be updated on Eik and new builds that use the import map get the updated map without changing their configuration.

[leftieFriele]

Suggested change

	Should you have one import for all your shared dependencies, or should you have several? That's up to you.
	Should you have one import for all your packages, or should you have several? That's up to you.

[leftieFriele]

Suggested change

	Import maps are versioned and can be aliased the same as any other asset on Eik. If you need to update a major version of a dependency you can create a new major version of the import map. However, updating a major version of a map means your users have to update their configuration.
	Import maps are versioned and can be aliased the same as any other asset on Eik. If you need to update a major version of a package you can create a new major version of the import map. However, updating a major version of a map means your users have to update their configuration.

[leftieFriele]

Suggested change

	If you have a dependency that's only used by a subset of your applications, consider having a separate import map for that dependency and its ecosystem of related modules. That way any major changes in that import map don't needlessly affect applications that don't use that dependency.
	If you have a package that's only used by a subset of your applications, consider having a separate import map for that dependency and its ecosystem of related modules. That way any major changes in that import map don't needlessly affect applications that don't use that dependency.

[leftieFriele]

The difference between the package types isn't really explained in the eik.json documentation. It mentions it's to avoid collisions, which makes sense for map and npm.
However there is no explanation for package being a type. Given that it's a bit of a strange name I think we should mention explain here exactly what the intention with especially package is.

[wkillerud]

It's really only to avoid collision, as far as I can tell. It's explained it's intended for application code in the paragraph below.

Application code should be published to the package namespace. This is also the default, if no other type is configured in eik.json.

[wkillerud]

@eik/node-client should probably get its own page under Reference

[wkillerud]

I pushed some new content:

• A page about @eik/node-client
• A page about shipping import maps from Eik to use browser import mapping
• Reworked the landing page after @leftieFriele's feedback