@contextualcode/fratomic-alivue NPM

Fratomic Alivue

Use Fratomic Alive Vue project to breathe life into your atoms and organisms.

Allows to build live single page website that uses Vue 3 components and API data. Optionally, can be deployed with Server-Side Rendering.

Installation

Make sure you have Vue CLI and Fratomic CLI installed.
Open empty directory of your project, and run:

npm install --save @contextualcode/fratomic-alivue
npx alivue-init
npm install

This should be one-time action, feel free to edit generated files. In most cases, you'll need to update App.vue component and add header, footer, etc.

Update fractal.config.js file to contain details about your project.

Usage

You can use full vue file definition, as in "address.vue". Or, you can keep it short with template only, as in "button.vue". For shortened version, fratomic-alivue will generate script tag automatically, based on "*.config.json" context.
To import components or modules outside of prototype, use @ alias.

import RequestHandler from '@/handler/RequestHandler';

Update your fratomic components (in prototype folder) configs to contain alivue configs where needed.

{
    "alivue": {
        "pageIdentifier": "frontpage",
        "pageIdentifier": ["frontpage", "folder"],
        "lazy": false,
        "chunkName": "search",
        "exclude": true,
        "routing": {
            "route": "/searchRequired",
            "name": "optionalName",
            "metaTitle": "(optional) Search page - Project Name",
            "metaKeywords": "(optional) find, search, look for result",
            "metaDescription": "(optional) This page allows search by keyword",
            "metaImageUrl": "(optional) https://somedomain.local/images/image.png"
        },
        "mock": [
            {
                "url": "GET /api/address_lines",
                "code": 200,
                "response": [{"text": "line 1"}, {"text": "line 2"}]
            },
            {
                "urlRegexp": "GET ^/api/address.*",
                "responseFile": "./api_response.json"
            },
            {
                "url": "POST /api/search",
                "params": {"query": "Test"},
                "code": 404,
                "response": {"searchItems": []}
            },
            {
                "url": "POST /api/search",
                "code": 200,
                "params": {"query": "ok"},
                "response": {"searchItems": [{"company": "ContextualCode"}]}
            }
        ],
        "context": {
            "_store": {
                "PageStore": {
                    "pageProps": {},
                    "pageMeta": {},
                    "pageComponentName": "folder"
                },
                "UserStore": {
                    "role": "admin",
                    "isLoggedIn": true
                }
            }
        }
    }
}

pageIdentifier can be array or string. Defines which page component use for an API response.
routing needed only if you want to display it without API URL.
lazy (default: true). Applicable only for pages and routes. true - loaded on demand. false - bundled with main app script.
exclude (default: false). If true - component excluded from build to live project.
chunkName (default: null). Applicable only for lazy pages and routes. null - unique chunk name generated, so bundled separately from others. "some-string" - bundled into named chunk, useful when components placed on the same page.
All parameters optional, and you can skip "alivue" too.
mock config implemented using axios-mock-adapter. Check it to see how options are used. Make sure you're using @/handler/RequestHandler axios instance for your API communication. Defaults - method: ANY, code: 200, response: "", params: {}
mock[0].url - accepts method + URL or URL (ANY method will be used). Methods: GET, POST, PATCH, PUT, ANY
mock[0].urlRegexp - same as url, but accepts regular expression to match URL
mock[0].code - response code
mock[0].params - Mocking a request with specific parameters. When using params, you must match all key/value pairs passed to that option.
mock[0].response - API response
mock[0].responseFile - file to load API response from, ralative to prototype component
context._store config designed to preconfigure Vuex state for component preview.

To preconfigure Vuex state globally for all components, use store field in prototype/alivue.config.json file. For example:

{
    "store": {
        "UserStore": {
            "user": {
                "first_name": "Ivan",
                "last_name": "Ternovtsiy"
            },
            "userLoaded": true
        }
    }
}

local context._store can be used to override globals.

Build client and server side dist

npm run build

Start fractal in sync mode, which will pick up updates in prototype files

npm run fractal-start-sync

Use this instead of fractal start --sync to make sure Vue files rebuilt too.

Update configuration in path/to/live-vue-project-name/.env.
Tip: You can use .env.local for local override.
Configure links to ignore in src/handler/PageHandler.js if needed.
We ignore links to pdf and image files by default.
By default, page data loaded from /api/${window.location.href} and expects structure like this:

{
    "type": "page type defined in `pageIdentifier`",
    "data": {
        "attribute name used as prop for the Component": "value",
        "metaTitle": "",
        "metaKeywords": "",
        "metaDescription": "",
        "metaImageUrl": ""
    }
}

Fields metaTitle, metaKeywords, metaDescription, metaImageUrl used to build page head tags, and removed from props by default.
If you prefer other API structure for component props or meta, you can customize it in src/handler/PageHandler.js.

Build and start fractal project

npm run fractal-start
# or, start fractal in sync mode
npm run fractal-start-sync

To build static version, use npm run build-static instead of fractal build
this will take care about proper index.html file creating

Usage without Server side rendering and with fallback to client-side rendering.

If you don't use SSR, update your src/main.js file to use createApp instead of createSSRApp.
this will reduce final JS file size and exclude client-side hydration code.
If you're using SSR and client-side as a fallback (while SSR is not available or down), update your public/index.html file. From <div id="app"></div> to <div id="app"><div style="display:none"></div></div>.
Otherwise, you'll see Cannot read property nodeType of null error in console while using createSSRApp without SSR content.

Styles & assets

Use ~@/ folder alias to include relative image in scss.

body {
    background-image: url('~@/assets/logo.png');
}

You can use both alias and relative import for scss files

@import "./imported";
@import "~@/assets/scss/imported";

Be aware we have configured PurgeCSS plugin. Check how it's configured in boilerplate/vue.config.js and check https://purgecss.com/configuration.html#configuration-file for more configuration options. You may need to add some css rules to the safelist option.

Docker usage

Update image: registry.gitlab.com/contextualcode/project/express in docker/docker-compose.yml
Use express for SSR version (recommended), or nginx to serve without SSR

cd docker
docker-compose build express
docker push registry.gitlab.com/contextualcode/project/express

docker-compose up express
# or:
docker run -d -p 80:3000 registry.gitlab.com/contextualcode/project/express

@frctl/fractal path vue @vue/compiler-sfc @vue/cli-service @vue/server-renderer

3 years ago

3 years ago

3 years ago

3 years ago

3 years ago