@magic404 - not found
@magic@magic@magicmagic concepts. These are the building blocks of every module in a magic app
modules are the main building block of magic.
a page is a module, a button is a module, a link is a module, an image is a module. a @magic app contains modules containing modules that contain modules. this can lead to inception.
state is a javascript object.
state can be mutated by actions or effects.
every rendering step, the state determines the output of the views
actions are an object containing functions
those functions get the state and their props and may return a new full, but changed, state.
effects are an object containing functions, just like actions.
they behave like actions, get a state and props and may return a new full, but changed, state.
the big difference? effects may be impure and trigger sideeffects outside of hyperapp.
views render the state to html
whenever an action triggers a change in the state, this then triggers a view change.
every module can have a style object attached to it.
magic will automagically merge all styles into one global css file.
in the future, it will also remove unused styles for you.
style merge order from lowest to highest, last overwrites first:
module.style < page.style < app.style < theme.style
internally, magic uses it's own css-in-js library.
to find out more, click the following link:
@magic/cssevery module can set a global object, containing state and action properties.
every state and/or action name in the global object with a value that equals true gets merged into the main app state/actions.
this is the serverside magic.
you can define functions that get transpiled into serverside lambdas.
server side lambdas will be available for GET and/or POST requests.
the server side function signature is (req, res) => {}, as in any nodejs http server, with the addition of req.body being async => awaited before execution of the lambda.
@magic
magic concepts. these are the building blocks of every module in a magic app
modules are the main building block of magic.
a page is a module, a button is a module, a link is a module, an image is a module. +even a theme is a module.
a @magic app contains modules containing modules that contain modules. +this can lead to inception.
state is a javascript object. +state can be mutated by actions, +effects and subscriptions can call actions to change the state. +every rendering frame, the state determines the output of the html views.
const state = {shown: false,count: 0,}
actions are an object containing functions
those functions get the state and their props and may return a new full, but changed, state.
const actions = {toggleModal: state => {return {...state,shown: !state.shown,}},calculator: {plus: state => ({ ...state, count: state.count + 1 }),minus: state => ({ ...state, count: state.count - 1 }),},}
effects are an object containing functions, just like actions.
effects can only change the state by calling actions.
effects may also be impure and trigger side-effects outside of hyperapp.
const effects = {waitASec: [state, async state => {await new Promise((r) => setTimeout(r, 1000))return actions.plus(state)}],}
at the moment, subscriptions can be defined using strings as function names.
also, if a module exports a subscriptions array, those subscriptions will be added to the app.
// in a module:export const lib = {subscribe: (dispatch, action) => {setInterval(() => {dispatch(action, { arg: Math.random() * 100 })})},}export const actions = {onSubscription: (state, e) => ({...state,arg: e.arg,})}export const subscriptions = ['lib.subscribe', 'actions.onSubscription']
views render the state to html +whenever an action triggers a change in the state, this then triggers a view change.
export const View = state => div(JSON.stringify(state))every module can export a style object. +magic will automagically merge all styles into one global css file. +in the future, it will also remove unused styles for you.
styles merge order, last overwrites first: +module.style < page.style < app.style < theme.style
this allows css to be inherited in both directions.
a module automatically creates it's own css namespace, +that same namespace can be used in page, app and theme css styles +to overwrite module specific styles.
internally, magic uses it's own css-in-js library.
to find out more, click the following link: +@magic/css
every module can set a global object, containing state and action properties.
every state and/or action name in the global object with a value that equals true gets merged into the main app state/actions, instead of into the module namespace.
// in module.mjsexport const state = {internal: 0,external: 0,}export const actions = {internal: state => ({...state,module: {internal: state.module.internal + 1,},}),external: state => ({...state,external: state.external + 1,}),}export const global = {state: {external: true},actions: {external: true,},}// in the view, we can use both the global and local actions and state variablesexport const View = state => div(['view',p({ onclick: actions.module.internal }, ['internal:', state.module.internal]),p({ onclick: actions.external }, ['external:', state.external]),])
this is the serverside magic. +you can define functions that get transpiled into serverside lambdas. +server side lambdas will be available for GET and/or POST requests.
the server side function signature is (req, res) => {}, +as it is in most nodejs http servers, +with the addition of req.body being async => awaited before execution of the lambda.
@magicThere are multiple magic files and directories.
the pages dir contains the pages of your webapp.
each page has it's own state and actions, but also inherits the global state and actions from the app and it's dependencies
/pages/index.mjs === http://mag.ic//pages/pageName.mjs === http://mag.ic/pageName//pages/page-name.mjs === http://mag.ic/page-name//pages/page_name.mjs === http://mag.ic/page_name//pages/dir/index.mjs === http://mag.ic/dir//pages/dir/name.mjs === http://mag.ic/dir/name/
export default {state: {variable: 'test',},actions: {changeVar: () => ({ variable: 'changed' }),},style: {'.cl': {color: 'green',},},View: state => div({ class: 'cl' }, ['this is the page content.',state.variable,]),}
the assets dir contains custom components of your app.
you can additionally import @magic-modules here
export default {Custom: () => div('custom component'),Pre: require('@magic-modules/pre),'}
the static dir contains all of your static assets.
every file in this directory gets copied to the public dir.
image and svg files get minified using imagemin
text and binary files get compressed using the optional node-zopfli-es (if it is installed)
the themes directory contains... themes.
a magic theme is an object of css rules, see @magic/css for more examples and documentation.
export default {'body': {color: 'blue',},}
the /app.mjs file allows you to set global state, actions, and styles
export default {state: {globalStateVar: 'globally available',},actions: {globalAction: () => ({ globalStateVar: 'overwritten.' }),},style: {'body': {color: 'green',},},}
the /config.mjs file allows you to set various aspects of your app
export default {ROOT: 'example',THEME: 'blue',WEB_ROOT: '/core/',// this option adds the// 'X-Clacks-Overhead', 'GNU Terry Pratchet'// http header// see http://www.gnuterrypratchett.com/FOR_DEATH_CAN_NOT_HAVE_HIM: true,// default CLIENT_LIB_NAME, overwrite to change names of transpiled css and js filesCLIENT_LIB_NAME: 'magic',}
@magic
There are multiple magic files and directories.
the pages dir contains the pages of your webapp.
each page has it's own state and actions, but also inherits the global state and actions from the app and it's dependencies
for the domain mag.ic:
/pages/index.mjs === http://mag.ic//pages/pageName.mjs === http://mag.ic/pageName//pages/page-name.mjs === http://mag.ic/page-name//pages/page_name.mjs === http://mag.ic/page_name//pages/dir/index.mjs === http://mag.ic/dir//pages/dir/name.mjs === http://mag.ic/dir/name/
Pages can use javascript, html or markdown
A magic javascript page is a @magic-module. The only difference is that pages get exposed via http
export const View = state =>div({ class: 'cl' }, ['this is the page content.',state.variable,])export const state = {variable: 'test',}export const actions = {changeVar: state => ({ ...state, variable: 'changed' }),}export const style = {'.cl': {color: 'green',},}
html pages can only export state and View.
---@state{"title": "html file example","description": "this module gets imported from a html file."}---<h2>${ state.title }</h4><p>{{ state.description }}</p>
markdown pages can only export state and View.
---@state {"title": "markdown file example","description": "markdown file description"}---## ${state.title}${state.description}
the assets dir contains custom components of your app.
you can import additional @magic-modules here
export default {Custom: () => div('custom component'),Pre: require('@magic-modules/pre),}
the static dir contains all of your static assets.every file in this directory gets copied to the public dir.image and svg files get minified using imagemin.
text and binary files get compressed using the optional node-zopfli-es (if it is installed)
the themes directory contains...themes.
a magic theme is an object of css rules, see @magic/css for more examples and documentation.
export default {'body': {color: 'blue',},}
the /app.mjs file allows you to set global state, actions, and styles
export const state = {globalStateVar: 'globally available',}export const actions = {globalAction: () => ({ globalStateVar: 'overwritten.' }),}export const style = {'body': {color: 'green',},}
the /config.mjs file allows you to set various aspects of your app
export default {// the local root directory of the magic appROOT: 'example',// gets suffixed to the url. in this case domain.com/core/ will be the page root.WEB_ROOT: '/core/',// the theme in use, lives in {ROOT}/assets/themes/{name} or can be installed as either '@magic-themes/{name}' or 'magic-theme-{name}'THEME: 'docs',// the full url of the page.URL: 'magic.github.io/core/',// the public dir the bundles get written toPUBLIC: 'docs',// the directory in the pages directory that holds the blog posts// if this is not set, no blog is created.BLOG_DIR: 'news',// append these modules after the app loaded and only if javascript is enabled.// can be used to add features that won't do anything without js anyways.HOIST: ['LightSwitch', 'NoSpy'],// default CLIENT_LIB_NAME, overwrite to change names of transpiled css and js filesCLIENT_LIB_NAME: 'magic',// this is set to be able to test broken link behaviour.// DO NOT ENABLE IN YOUR APP (unless you need to because reasons...)NO_CHECK_LINKS_EXIT: true,// tags written to the html before the #magic containerPREPEND_TAGS: [{ name: 'div', props: { id: 'PREPENDTag' } }],// tags written to the html after the #magic containerAPPEND_TAGS: [{ name: 'div', props: { id: 'APPENDTag' } }],// script files, embedded before the magic.js scriptPREPEND_SCRIPTS: ['/prependScript.js'],// script files, embedded after the magic.js scriptAPPEND_SCRIPTS: ['/appendScript.js'],// js files that get written directly into the magic.js script, before the magic code.PREPEND_JS: ['/prependJs.js'],// js files that get written directly into the magic.js script, after the magic code.APPEND_JS: ['/appendJs.js'],// css written into the magic.css file, before the magic css// use this to set defaults that get overwritten by the generated app cssPREPEND_CSS: ['/prependCss.css'],// css written into the magic.css file, after the magic css// use this to overwrite the generated app cssAPPEND_CSS: ['/appendCss.css'],// add additional static file directories that will get added to app.static[name]ADD_STATIC: ['node_modules/dir/name/'],// this option adds the// 'X-Clacks-Overhead', 'GNU Terry Pratchet'// http header// see http://www.gnuterrypratchett.com/FOR_DEATH_CAN_NOT_HAVE_HIM: true,}
@magicthe goal of this document is to give you a rough @magical overview.
@magic aims to make it easy to stitch together any kind of webapp. by providing simple, well documented and self contained modules, @magic makes it possible to create stunningly fast webpages with minimal cognitive overhead.
@magic does not spy.
not only do we try to be legally compliant by default, but we also aim to be ethical which means prioritizing your rights over our needs, but also means we prioritize the rights of your users over your needs. we believe that this is the best compromise.
~4 kb javascript boilerplate. usually, all the javascript in your homepage will be 30-60kb big (after unpacking), 10-30kb get transmitted from the server to the client. this documentation page you are reading loads about 15kb of javascript, which, when parsing, turns into 40kb of uncompressed javascript.
most of the functionality works without javascript, some buttons and realtime user interactions obviously won't, but @magic always tries to provide a non-javascript fallback via css.
this makes free hosting (using github or gitlab pages) possible. and it's easy.
@magic publishes to github, gitlab and any other git-pages enabled hosting service.
automagically generates serverless lambdas, derived from the @magic-modules you use in your pages. this makes visitor statistics, user authentication and authorization, chat, and all other server side services possible.
@magic
@magic/core documentation. tells you why, how and when to use @magic. also provides an overview of all @magic functionality this ecosystem provides.
the goal of this document is to give you a rough @magical overview.
@magic aims to make it easy to stitch together any kind of webapp. +by providing simple, well documented and self contained modules, +@magic makes it possible to create stunningly fast +webpages with minimal cognitive overhead.
@magic does not spy.
not only do we try to be legally compliant by default, +but we also aim to be ethical +which means prioritizing your rights over our needs, +but also means we prioritize the rights of your users over your needs. +we believe that this is the best compromise.
~4 kb javascript boilerplate. +usually, all the javascript in your homepage will be 30-60kb big (after unpacking), +10-30kb get transmitted from the server to the client. +this documentation page you are reading loads 20kb of gzipped javascript, +which, when parsing, turns into ~88kb of uncompressed javascript. +this includes all content of all subpages, no additional server requests needed for any navigations in the page.
WIP: code splitting for bigger pages.
most of the functionality works without javascript, +some buttons and realtime user interactions obviously won't, +but @magic always tries to provide a non-javascript fallback via css.
this makes free hosting (using github or gitlab pages) possible. and it's easy.
@magic publishes to github, gitlab, +and any other git-pages enabled hosting service.
automagically generates +serverless lambdas, derived from the +@magic-modules +you use in your pages.
this makes visitor statistics, user authentication and authorization, +chat, and all other server side services possible.
@magic@magic/core libraries allow you to include client side functionality in your app.
what would javascript be without the millions of dependencies that you can easily install and make the average webpage slow[ly] (pun intended) grow towards a footprint of 5 megabytes.
we think that all of that bloat is unneeded, unheeded and, frankly, not optimal.
magic has one external client side dependency, hyperapp, [~400 lines that provide our ui state machine]. thats it. and it won't change.
we also have the tendency to write libraries specialized for our usecase, see @magic/css @magic/test @magic/cli and others.
once there is a lib key in at least one component, window.lib (browser) and global.lib (nodejs) will be set, aliasing lib as a global variable in both environments
if you need libraries in multiple otherwise independent modules, it might be easier to keep your library dependencies in a central place. to achieve this, one can simply create /assets/lib.mjs and export an object from it. this object will get merged into the globalThis.lib object making it available as "lib" throughout your app.
alternatively, you can create a /assets/modules directory and place UpperCaseNamed.mjs files in there. their names will be deferred from the filename and they will be available in your app without importing them. if you do not use one of the modules, dead code elimination will simply remove it in production.
export default { name: () => {} }lib.name = () => {}all @magic-libraries/* and all npm packages starting with magic-library-* will be loaded automatically.
first, install a @magic-library
npm install --save --save-exact @magic-libraries/isthen, in javascript
export const View = props => div(['value is ',lib.is(props.value, 'string') ? '' : 'not',' a string'])
key => value store using localstorage
the @magic-libraries/gql module encodes template strings to graphql queries ready to be sent to a server.
the @magic-libraries/is module unifies the javascript type testing apis.
the @magic-libraries/json module parses and stringifies json. it also returns errors instead of throwing them.
the @magic-libraries/prevent-default module invokes event.preventDefault as a hyperapp effect.
the @magic-libraries/uri module encodes objects to uri strings and decodes uri strings to objects.
@magic
@magic/core libraries allow you to include client side functionality in your app.
what would javascript be without the millions of dependencies +that you can easily install and make the average webpage +slow[ly] (pun intended) grow towards a footprint of 5 megabytes.
we think that all of that bloat is unneeded, unheeded and, frankly, not optimal.
magic has one external client side dependency, +hyperapp, +[~500 lines that provide our ui state machine]. thats it. and it won't change.
we also have the tendency to write libraries specialized for our usecase, see +@magic/css, +@magic/test, +@magic/cli +and others.
once there is a lib key in at least one component, +window.lib (browser) and global.lib (nodejs) will be set, +aliasing lib as a global variable in both environments
if you need libraries in multiple otherwise independent modules, +it might be easier to keep your library dependencies in a central place.
to achieve this, one can simply create /assets/lib.mjs and export an object from it. +this object will get merged into the globalThis.lib object, +making it available as "lib" throughout your app.
export default { name: () => {} }will turn into
lib.name = () => {}all @magic-libraries and all npm packages starting with magic-library-* will be loaded automatically
first, install a @magic-library
npm install --save --save-exact @magic-libraries/isthen, in javascript
export const View = props => div(['value is ',lib.is(props.value, 'string') ? '' : 'not',' a string',])
key => value store using localstorage
the @magic-libraries/gql module encodes template strings to graphql queries ready to be sent to a server.
http request effect for @magic.
the @magic-libraries/is module unifies the javascript type testing apis.
the @magic-libraries/json module parses and stringifies json. it also returns errors instead of throwing them.
the @magic-libraries/prevent-default module invokes event.preventDefault as a hyperapp effect.
makes strings url safe. opinionated.
the @magic-libraries/try-catch module returns errors instead of throwing them.
the @magic-libraries/uri module encodes objects to uri strings and decodes uri strings to objects.
@magicthis is Mod. it gets loaded from /assets/modules/Mod.mjs
the state of this module: {"test":"testing"}
Mod.Component, a second component in /assets/modules/Mod.mjs
export const View = state =>div({ class: 'Mod' }, [h3('Mod.Mod'),p(['this is Mod. it gets loaded from ',Link({ to: 'https://github.com/magic/core/blob/master/example/assets/modules/Mod.mjs' }, '/assets/modules/Mod.mjs'),' automatically, no need to import it.',]),p(['the state of this module: ', JSON.stringify(state.module)]),])export const state = {module: {test: 'testing',},}export const style = {margin: '0 0 1em',padding: '0.5em',border: '1px solid',borderColor: 'green',h3: {margin: 0,},}export const global = {state: {module: true,},}export const Component = props => {props = typeof props === 'string' ? { header: props } : propsCHECK_PROPS(props, propTypes, 'ModComponent')const header = props.header || props.titlereturn div({ class: 'ModComponent' }, [header && h5(header),p(['Mod.Component, a second component in ',Link({ to: 'https://github.com/magic/core/example/assets/module.mjs' }, '/assets/module.mjs'),]),])}Component.style = {border: '1px solid orange',}export const propTypes = {ModComponent: [{ key: 'header', type: ['string', 'array'], required: ['title'] }],}