Simprakit Library Mini Docs

Structure

Folders and files in this project:

1. /src/components - all components the library exposes. Component names should be prefixed with "Sk".
2. /src/components/**/styles.module.scss - Styles for each component. Styles should utilize use css variables so that when a theme css file is loaded into the document component colors change.
3. /src/exports.ts - exports components for library consumers to import from "simprakit"
4. /src/react-exports.ts - exports components for library consumers who are using react to import. They will need to import the components from "simprakit/react"
5. /src/themes/ - Theme css files go here. Components consume the css variables defined in this file.
6. /playground/ - you can develop and test components here when you run npm run dev.

Setup

Install dependencies:

npm i

Dev Server

To start the dev server run (by default on localhost:5077):

npm run dev

Build

In this repo TypeScript compiler is used to produce JavaScript that runs in modern browsers. Also, ESLint is used along with it - they are executed in fix mode before every build. So, you might want to configure linting rules in .eslintrc.js to make them fit your code style.

To build the library (output files will be in build folder) run:

npm run build

Locally importing the library in another project

In simprakit's directory, run:

npm link

Then, in the react/vue/vanillajs project where you want to test the library, run:

npm link simprakit 

Now the library is added to the project's node_modules folder. When you make changes to library code, you need to run npm run build again for changes to apply. Warning: If something isn't working, check node_modules of your project to see if @simprakit is there. If it's not, re-run npm link simprakit.

CAVEATS

Make sure your server serves the node_modules folder, so that the library can request component chunks dynamically. e.g. for express:

a.use('/node_modules', express.static('node_modules'));

If you are using vite dev server, you don't need to do this as it already serves the node_modules folder by default.

If you are using webpack and your own node server, you may encounter issues related to resolving the external library react. This usually produces "Error: Invalid hook call" or "Cannot find module 'react'". To fix this: Set resolve.symlinks option in your webpack config to false. Also, make sure there's no react installed in this library's node_modules. If react is in devDependencies, it may cause issues.

Vue users should see this page before being able to use web components inside their project: https://vuejs.org/guide/extras/web-components

Recommended config for vue with vite:

// vite.config.js
import vue from '@vitejs/plugin-vue'

export default {
  plugins: [
    vue({
      template: {
        compilerOptions: {
          // treat all tags with a sk- as custom elements
          isCustomElement: (tag) => tag.startsWith('sk-')
        }
      }
    })
  ]
}

Usage

Example usage for vue:

<script setup lang="ts">
    import { config } from "simprakit/config"
    import { SkHelloText } from "simprakit"
    import { SkByeText } from "simprakit"
    SkByeText()
    SkHelloText()

    config.setTheme("dark")

    const toggleTheme = () => {
        config.setTheme(config.theme === 'dark' ? 'light' : 'dark')
    }
</script>

<template>
    <sk-hello-text name="this text gets its color from --color-common css variable. Try changing the theme">World</sk-hello-text>
    <sk-bye-text name="this text gets its color from --color-common css variable. Try changing the theme">World</sk-bye-text>

    <button @click="toggleTheme"> Change Theme </button>
</template>

Example usage for React:

import { config } from "simprakit/config"
import { Suspense } from 'react'
import { SkHelloText } from "simprakit/react"
import { SkByeText } from "simprakit/react"

function App() {
    config.setTheme("dark")

    const toggleTheme = () => {
        config.setTheme(config.theme === 'dark' ? 'light' : 'dark')
    }

    return (
        <>
            <Suspense fallback={<div>Optional Loading Skeleton To Show While Component's chunk is being fetched...</div>}>
                <SkHelloText name="this changes color depending on theme">world</SkHelloText>
            </Suspense>
            <SkByeText name="this changes color depending on theme">world</SkByeText>
            <br/>
            <button onClick={toggleTheme}>Toggle Theme</button>
        </>
    )
}

export default App