Skip to content

Commit ca373b2

Browse files
Ibrahim-HaizelIbrahim-Haizel
committed
update readme and get started documentation
1 parent 0d2fec0 commit ca373b2

File tree

3 files changed

+112
-202
lines changed

3 files changed

+112
-202
lines changed

‎README.md‎

Lines changed: 89 additions & 95 deletions
Original file line numberDiff line numberDiff line change
@@ -1,58 +1,40 @@
1-
# Quick Start Installation
1+
# MHCLG Svelte Component Library
22

3-
Because this package is currently privately published to the GitHub npm package registry, you'll need to log in to the package registry before you can install the package. To log in you'll need your GitHub username and a personal access token with the correct permissions.
3+
A comprehensive component library for government digital services, built with Svelte 5 and following GOV.UK Design System principles.
44

5-
## 1. To get your personal access token on GitHub, follow these steps:
5+
## Prerequisites
66

7-
1. **Log in to GitHub**: Go to your GitHub account.
8-
2. **Navigate to Developer Settings**:
9-
* Click on your profile photo in the upper-right corner of the page.
10-
* Select Settings.
11-
* In the left sidebar, click Developer settings.
12-
3. **Access Personal Access Tokens**:
13-
* Under the Personal access tokens section in the sidebar, click either Tokens (classic) or Fine-grained tokens, depending on your preference.
14-
4. **Generate a New Token**:
15-
* Click Generate new token (for classic tokens, select Generate new token (classic)).
16-
* Provide a descriptive name in the "Note" field.
17-
* Set an expiration date if needed.
18-
* Choose the required scopes or permissions for the token. For installing the package, we will need "write:packages" (Upload packages to GitHub Package Registry), "read:packages" (Download packages from GitHub Package Registry) and "repo".
7+
This component library is designed for use with:
198

20-
5. **Generate and Save the Token**:
21-
* Click Generate token.
22-
* Optionally, copy the new token to your clipboard for immediate use. Make sure to save it securely, as you won’t be able to view it again.
9+
- **SvelteKit projects** - The components are built for SvelteKit applications
2310

24-
## 2. Next, you will need to add the GitHub registry path to the npm config file `.npmrc` so that npm knows to look for the package we want to authenticate for within the GitHub registry rather than the npm website.
11+
- **Svelte 5** - Components use the latest Svelte 5 syntax and runes
2512

26-
1. Add this line to the `.npmrc` file: `@communitiesuk:registry=https://npm.pkg.github.com`
13+
## Documentation and Examples
2714

28-
## 3. Now we can log in:
15+
Visit our [component library documentation](https://communitiesuk.github.io/mhclg_svelte_component_library/) for:
2916

30-
1. Enter the following command into the terminal:
31-
```bash
32-
npm login --scope=@communitiesuk --auth-type=legacy --registry=https://npm.pkg.github.com
33-
```
34-
2. Enter your GitHub username, followed by the PAT token we obtained in the previous step as the password. When copying the token into the terminal, it may not be visible. Press the "Enter" key regardless and it should submit.
17+
- Interactive component examples
18+
- API documentation
19+
- Usage patterns and best practices
20+
- Installation guides
3521

36-
> Username: USERNAME
37-
> Password: TOKEN
22+
## Quick Start Installation
3823

39-
More information about the GitHub npm registry can be found here: [https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry)
24+
The package is publicly available on npm:
4025

41-
## 4. Now you are logged in, you can install the package:
42-
43-
1. Enter the npm install command for this package, using the latest version. The package should start installing.
26+
```bash
27+
npm install @communitiesuk/svelte-component-library@latest
28+
```
4429

45-
To import a component from the newly installed package, you can add an import statement in the following structure to your Svelte page file:
30+
## Usage
4631

47-
```javascript
48-
import { InternalHeader, NotificationBanner, WarningText, SearchAutocomplete, Accordion} from "@communitiesuk/svelte-component-library";
49-
```
32+
### GOV.UK Frontend Styles
5033

51-
See the documentation app for examples of how to use the imported components.
34+
To ensure GOV.UK styles are applied correctly, add this script tag to your `app.html` file in the body section:
5235

53-
2. To make sure govuk styles are applied correctly add this script tag to the app.html body tag section:
36+
```html
5437

55-
```javascript
5638
<script>
5739
document.body.className +=
5840
" js-enabled" +
@@ -61,9 +43,26 @@ See the documentation app for examples of how to use the imported components.
6143
: "");
6244
</script>
6345
```
46+
47+
This is required because the GOV.UK Frontend CSS checks the document body for JavaScript availability to progressively enhance components.
48+
49+
### Importing Components
50+
51+
Import components directly from the package:
52+
53+
```javascript
54+
import {
55+
InternalHeader,
56+
NotificationBanner,
57+
WarningText,
58+
SearchAutocomplete,
59+
Accordion,
60+
} from "@communitiesuk/svelte-component-library";
61+
```
62+
6463
# Releasing a new version of the Svelte Component Library
6564

66-
This guide outlines the steps to bump the version of your package, tag the release in Git, and push it to prepare for publishing.
65+
This guide outlines the steps to bump the version of your package, tag the release in Git, and publish to npm.
6766

6867
## 1. Commit Your Changes
6968

@@ -80,75 +79,80 @@ Make sure you are on your main development branch you want to release (e.g., `ma
8079

8180
Use the `npm version` command to update `package.json` and `package-lock.json`, create a commit, and create an annotated Git tag. Choose **one** of the following based on [Semantic Versioning (SemVer)](https://semver.org/):
8281

83-
* **Patch Release (Bug fixes, tiny changes - e.g., 0.1.8 -> 0.1.9):**
84-
```bash
85-
npm version patch
86-
```
87-
* **Minor Release (New features, backward-compatible - e.g., 0.1.8 -> 0.2.0):**
88-
```bash
89-
npm version minor
90-
```
91-
* **Major Release (Breaking changes - e.g., 0.1.8 -> 1.0.0):**
92-
```bash
93-
npm version major
94-
```
95-
* **Specific Version:**
96-
```bash
97-
npm version <new-version> # Replace <new-version> with the desired version, e.g., 1.2.3
98-
```
82+
- **Patch Release (Bug fixes, tiny changes - e.g., 1.0.0 → 1.0.1):**
9983

100-
## 3. Push Changes and Tags
84+
```bash
85+
npm version patch
86+
```
10187

102-
Push the commit and the new tag created by `npm version` to your remote Git repository (e.g., GitHub):
88+
- **Minor Release (New features, backwards compatible - e.g., 1.0.0 → 1.1.0):**
10389

104-
```bash
105-
git push && git push --tags
106-
```
90+
```bash
91+
npm version minor
92+
```
10793

108-
* `git push`: Pushes the version commit.
109-
* `git push --tags`: Pushes the newly created version tag.
94+
- **Major Release (Breaking changes - e.g., 1.0.0 → 2.0.0):**
95+
```bash
96+
npm version major
97+
```
11098

111-
## 4. Publishing (Automatic via GitHub Actions)
99+
This command will:
112100

113-
Now the tag has been pushed, we can create a release on GitHub to trigger the GitHub Actions workflow defined in `.github/workflows/npm-publish-github-packages.yml`, which will handle the actual `npm publish` step to GitHub Packages.
101+
- Update the version number in `package.json` and `package-lock.json`
102+
- Create a new commit with the version bump
103+
- Create a Git tag with the new version number
114104

115-
Click on "create new release" from the repo homepage.
105+
## 3. Push Changes and Tags
116106

117-
Choose the target branch that you want to release (e.g. main).
107+
Push the commit and the new tag created by `npm version` to the remote Git repository (e.g., GitHub):
118108

119-
Choose the tag version pushed to GitHub in a previous step.
109+
```bash
110+
git push && git push --tags
111+
```
120112

121-
Click generate release notes, and add any additional write-up to describe the changes in this release.
113+
- `git push`: Pushes the version commit.
114+
- `git push --tags`: Pushes the newly created version tag.
122115

123-
Amend the release title to something appropriate, including the version number in the title.
116+
## 4. Create a GitHub Release
124117

125-
Click "Set as pre-release" given the package is not stable yet.
118+
1. Go to the GitHub repository
119+
2. Click on "Releases" in the right sidebar
120+
3. Click "Create a new release"
121+
4. Select the tag you just created (e.g., `v1.0.1`)
122+
5. Add a release title and description
123+
6. Click "Publish release"
126124

127-
Click the publish release button.
125+
## 5. Automatic Publishing
128126

129-
If you now go to the "Actions" tab in the repo's horizontal nav bar, you'll see the publish workflow being triggered. Once complete, the package will be uploaded and the new version can be installed.
127+
Once you create the GitHub release, If you now go to the "Actions" tab in the repo's horizontal nav bar, you'll see the publish workflow being triggered. The GitHub Actions workflow (`.github/workflows/npm-publish.yml`) will automatically:
130128

131-
# create-svelte
129+
- Build the package
130+
- Publish it to npm public registry
131+
- Make it available for installation via `npm install @communitiesuk/svelte-component-library`
132132

133-
Everything you need to build a Svelte library, powered by [`create-svelte`](https://github.com/sveltejs/kit/tree/main/packages/create-svelte).
133+
## 6. Verify the Release
134134

135-
Read more about creating a library [in the docs](https://svelte.dev/docs/kit/packaging).
135+
After the GitHub Action completes, verify that your package was published successfully:
136136

137-
## Creating a project
137+
1. Check the [npm package page](https://www.npmjs.com/package/@communitiesuk/svelte-component-library)
138+
2. Try installing the new version in a test project:
139+
```bash
140+
npm install @communitiesuk/svelte-component-library@latest
141+
```
138142

139-
If you're seeing this, you've probably already done this step. Congrats!
143+
## Notes
140144

141-
```bash
142-
# create a new project in the current directory
143-
npx sv create
145+
- Only create releases from the "main" branch to ensure stability
146+
- Always test changes thoroughly before creating a release
147+
- Consider creating pre-release versions for testing: `npm version prerelease --preid=alpha`
144148

145-
# create a new project in my-app
146-
npx sv create my-app
147-
```
149+
# Developing and Building Commands
150+
151+
This project is built with [`create-svelte`](https://github.com/sveltejs/kit/tree/main/packages/create-svelte). Read more about creating a library [in the docs](https://svelte.dev/docs/kit/packaging).
148152

149153
## Developing
150154

151-
Once you've created a project and installed dependencies with `npm install` (or `pnpm install` or `yarn`), start a development server:
155+
Start a development server:
152156

153157
```bash
154158
npm run dev
@@ -176,13 +180,3 @@ npm run build
176180
You can preview the production build with `npm run preview`.
177181

178182
> To deploy your app, you may need to install an [adapter](https://svelte.dev/docs/kit/adapters) for your target environment.
179-
180-
## Publishing
181-
182-
Go into the `package.json` and give your package the desired name through the `"name"` option. Also, consider adding a `"license"` field and point it to a `LICENSE` file which you can create from a template (one popular option is the [MIT license](https://opensource.org/license/mit/)).
183-
184-
To publish your library to [npm](https://www.npmjs.com):
185-
186-
```bash
187-
npm publish
188-
```

‎src/routes/get-started/+page.svelte‎

Lines changed: 22 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -37,79 +37,9 @@
3737

3838
<h2 class="govuk-heading-l govuk-!-margin-top-8">Installation</h2>
3939

40-
<WarningText
41-
assistiveText="Warning"
42-
text="This package is currently privately published to the GitHub npm package registry. You'll need to authenticate before installation."
43-
/>
44-
45-
<h3 class="govuk-heading-m govuk-!-margin-top-6">
46-
Step 1: Create a GitHub Personal Access Token
47-
</h3>
48-
49-
<ol class="govuk-list govuk-list--number">
50-
<li>Log in to your GitHub account</li>
51-
<li>
52-
Navigate to <strong>Settings</strong> →
53-
<strong>Developer settings</strong>
54-
→ <strong>Personal access tokens</strong>
55-
</li>
56-
<li>Click <strong>Generate new token</strong> (classic)</li>
57-
<li>Provide a descriptive name and set expiration if needed</li>
58-
<li>
59-
Select the following scopes:
60-
<ul class="govuk-list govuk-list--bullet govuk-!-margin-top-2">
61-
<li>
62-
<code>write:packages</code> - Upload packages to GitHub Package Registry
63-
</li>
64-
<li>
65-
<code>read:packages</code> - Download packages from GitHub Package Registry
66-
</li>
67-
<li><code>repo</code> - Repository access</li>
68-
</ul>
69-
</li>
70-
<li>Click <strong>Generate token</strong> and save it securely</li>
71-
</ol>
72-
73-
<h3 class="govuk-heading-m govuk-!-margin-top-6">
74-
Step 2: Configure npm registry
75-
</h3>
76-
77-
<p class="govuk-body">
78-
Add the GitHub registry path to your <code>.npmrc</code> file:
79-
</p>
80-
81-
<CodeBlock
82-
code={codeBlocks.npmrcConfig}
83-
language="bash"
84-
filename=""
85-
extension=".npmrc"
86-
/>
87-
88-
<h3 class="govuk-heading-m govuk-!-margin-top-6">
89-
Step 3: Authenticate with npm
90-
</h3>
91-
92-
<p class="govuk-body">Run the following command in your terminal:</p>
93-
94-
<CodeBlock
95-
code={codeBlocks.npmLogin}
96-
language="bash"
97-
filename="Terminal"
98-
extension=""
99-
theme="github-dark"
100-
/>
101-
102-
<p class="govuk-body">
103-
Enter your GitHub username and use your Personal Access Token as the
104-
password.
105-
</p>
106-
107-
<h3 class="govuk-heading-m govuk-!-margin-top-6">
108-
Step 4: Install the package
109-
</h3>
110-
11140
<p class="govuk-body">
112-
Install the latest version of the component library:
41+
The component library is publicly available on npm, making installation
42+
straightforward:
11343
</p>
11444

11545
<CodeBlock
@@ -122,24 +52,11 @@
12252

12353
<h2 class="govuk-heading-l govuk-!-margin-top-8">Usage</h2>
12454

125-
<InsetText>
126-
{#snippet content()}
127-
The component library includes all necessary CSS and JavaScript files.
128-
When you install the package, GOV.UK Frontend styles & assets as well as
129-
custom styles and assets are automatically included out of the box.
130-
{/snippet}
131-
</InsetText>
132-
133-
<h3 class="govuk-heading-m govuk-!-margin-top-6">Importing components</h3>
134-
135-
<p class="govuk-body">Import components in your Svelte files:</p>
136-
137-
<CodeBlock
138-
code={codeBlocks.importComponents}
139-
language="javascript"
140-
filename="App"
141-
extension=".svelte"
142-
/>
55+
<p class="govuk-body">
56+
The component library includes all necessary CSS and JavaScript files.
57+
When you install the package, GOV.UK Frontend styles & assets as well as
58+
custom styles and assets are automatically included out of the box.
59+
</p>
14360

14461
<h3 class="govuk-heading-m govuk-!-margin-top-6">
14562
Enable GOV.UK Frontend styles
@@ -167,6 +84,17 @@
16784
extension=".html"
16885
/>
16986

87+
<h3 class="govuk-heading-m govuk-!-margin-top-6">Importing components</h3>
88+
89+
<p class="govuk-body">Import components in your Svelte files:</p>
90+
91+
<CodeBlock
92+
code={codeBlocks.importComponents}
93+
language="javascript"
94+
filename="App"
95+
extension=".svelte"
96+
/>
97+
17098
<h2 class="govuk-heading-l govuk-!-margin-top-8">Next steps</h2>
17199

172100
<ul class="govuk-list govuk-list--bullet">
@@ -206,12 +134,10 @@
206134
</ul>
207135

208136
<div class="govuk-!-margin-top-6">
209-
<InsetText>
210-
{#snippet content()}
211-
This is an alpha release. The API may change as we continue to develop
212-
and improve the library based on user feedback.
213-
{/snippet}
214-
</InsetText>
137+
<WarningText
138+
text="This is an alpha release. The API may change as we continue to develop
139+
and improve the library based on user feedback."
140+
/>
215141
</div>
216142

217143
<div class="govuk-!-margin-top-8">

0 commit comments

Comments
 (0)